Phone API Integrations

Relevant source files

The following files were used as context for generating this wiki page:

• cooltools/lib/phoneApi.ts
• cooltools/app/page.tsx
• cooltools/app/phones/[slug]/page.tsx
• cooltools/app/compare/page.tsx
• cooltools/shared/schema.ts
• cooltools/lib/utils.ts

Introduction

The Phone API Integration system serves as the primary data acquisition layer for the CoolTools platform. Its purpose is to interface with external mobile specification providers to retrieve comprehensive data regarding phone brands, latest releases, and detailed technical specifications. This module enables the application to offer comparison features, advanced search capabilities, and price tracking by normalizing external data into internal structures.

The system is built around a centralized API utility library that handles asynchronous requests, implements caching strategies to optimize performance, and provides robust error handling with retry logic. This ensures that the frontend components, such as the Phone Details Page and Comparison Module, have reliable access to high-fidelity device data.

API Architecture and Core Logic

The integration layer is primarily implemented in cooltools/lib/phoneApi.ts. It utilizes axios for HTTP communication with the base provider https://api-mobilespecs.azharimm.dev.

Caching and Request Deduplication

To reduce latency and minimize redundant network calls, the system implements two critical patterns:

1. In-Memory Cache: A Map object stores results with a Time-To-Live (TTL) of 5 minutes.
2. Request Deduplication: A pendingRequests Map tracks active Promises. If a request for the same resource is initiated while another is still in progress, the system returns the existing Promise instead of creating a new one.

Sources: cooltools/lib/phoneApi.ts:5-23, cooltools/lib/phoneApi.ts:145-148

Sequence of Data Retrieval

The following diagram illustrates the flow of a typical data request, including cache checks and retry attempts.

Data Models and Interfaces

The integration defines strict TypeScript interfaces to ensure type safety across the application. These interfaces map the JSON responses from the external API to usable frontend objects.

Interface	Key Fields	Description
PhoneSpec	phone_name, brand, display, platform, memory, battery	Comprehensive technical details for a specific device.
PhoneListItem	phone_name, phone_url, phone_image, detail	Summary data used in lists and search results.
PhoneBrand	brand_id, brand_name, device_count	Metadata for phone manufacturers.

Sources: cooltools/lib/phoneApi.ts:25-96

Functional Endpoints

The system exposes several high-level functions used by various pages in the application.

Search and Discovery

• searchPhones(query): Performs a keyword search across the device database. Used in the Comparison page and Advanced Search.
• getLatestPhones(): Fetches the most recently added devices. Powering the "Latest Releases" section on the home page.
• getTopPhones(): Retrieves devices based on interest metrics.

Sources: cooltools/lib/phoneApi.ts:121-137, cooltools/app/page.tsx:29-35

Brand and Category Integration

• getAllBrands(): Retrieves a list of all supported manufacturers.
• getPhonesByBrand(brandSlug, page): Supports paginated retrieval of devices filtered by brand.

Sources: cooltools/lib/phoneApi.ts:98-119

Phone Details Integration

The details integration consumes the getPhoneDetails function to populate the [slug] dynamic route. It organizes the PhoneSpec data into three primary views: Specifications, Features, and Network.

Specification Mapping

The system maps the nested objects within PhoneSpec to UI sections:

• display: size, resolution, and type.
• platform: chipset, CPU, and GPU.
• memory: internal storage and RAM.
• main_camera & selfie_camera: arrays of camera specifications.

Sources: cooltools/app/phones/[slug]/page.tsx:142-243

Comparison System Integration

The comparison module allows users to select up to 4 devices. It uses the API integration to fetch details for multiple slugs simultaneously using Promise.allSettled.

Internal Database Schema Comparison

While the API integration handles real-time data from external sources, the project defines a parallel internal schema in cooltools/shared/schema.ts for persistence, such as user reviews and price history.

Table	Relation	Purpose
phones	Primary Entity	Mirrors API data for internal indexing and scoring (AnTuTu, Camera Score).
price_history	References phones.id	Tracks historical pricing for specific devices over time.
benchmarks	References phones.id	Stores specific test results like Geekbench or 3DMark.

Sources: cooltools/shared/schema.ts:4-106

Utility Support

The API integration is supported by utility functions that normalize data strings returned by the external provider.

• formatPrice: Extract numeric values and formats as USD.
• extractNumericValue: Used for comparing specs like battery capacity (mAh) or screen size.

Sources: cooltools/lib/utils.ts:20-42

Conclusion

The Phone API Integration module is a robust data-fetching layer that abstracts the complexities of external API communication. By implementing caching, request deduplication, and retry logic, it provides a stable foundation for the CoolTools platform's high-density data features, including real-time search, multi-device comparison, and detailed technical specifications.