# 2. Time and Location Information

# Time and Region Specifications

This section explains the time specifications (time zone/date format) and region parameters (region/language) of the FoxData API to help callers maintain consistency during data display, reconciliation, caching, and task scheduling.

---

## 1. Data Time Zone Specifications (UTC)

- The FoxData API **consistently uses the UTC time zone** as the standard for data aggregation and returns.
- If your business system uses a local time zone (e.g., Beijing Time UTC+8), please perform time zone conversion yourself during display or reconciliation.
- For regions with daylight saving time (e.g., parts of the United States), **UTC remains the standard** to avoid date boundary ambiguities caused by daylight saving time.

---

## 2. Time Field Formats

Different APIs may use different time field formats; always refer to the API documentation. Common formats include:

- **Date (date)**: `YYYY-MM-DD` (Example: `2025-12-18`)
- **Timestamp**: Second-level or millisecond-level timestamps (example: `1758909150000`). If the interface documentation is unclear, please refer to the examples provided.

> Recommendation: Standardize time parsing and formatting on the caller’s side to avoid confusion between seconds and milliseconds.

---

## 3. Time Range Parameters (start/end)

- If the API supports `start` / `end` (or `startTime` / `endTime`), these are generally used to specify a query range.
- **Range boundaries** (whether endpoints are included) are subject to the API documentation; if not explicitly stated, it is recommended to interpret them as “including the start and end dates” and perform result validation accordingly.

---

## 4. Region Parameter (region)

- `region` typically uses **country/region codes** (in uppercase), such as `US`, `GB`, or `CN`.
- The coverage of `region` may vary across different modules; refer to the corresponding API documentation.

---

## 5. Language Parameter (language)

- A single country/region may support multiple languages, and **the language codes used by the App Store and Google Play differ**:
  - **App Store**: Commonly uses a hyphenated format (e.g., `en-GB`)
  - **Google Play**: Commonly uses an underscore format (e.g., `en_GB`)
- If the `language` parameter is not included in the request (or is left empty), the system will process the request using the default language for that `region`.

For the language mapping table, please refer to the section: **“Region Language Mapping Table”**.