Requiresread_dataaccess scope.More access scope
The Get Data Analysis API retrieves analytical data for the specified time range and dimensions.
This enables users to:
- Analyze their shop's performance.
- Evaluate marketing efforts.
- Gain insights into user behavior.
Request Parameters
Public Request Parameters
Query Parameters
Field | Type | Required | Description | Example |
|---|---|---|---|---|
|
| Yes | The starting timestamp (in seconds) for retrieving analysis data. Must be a valid Unix timestamp and less than end_time. Logic |
|
|
| Yes | The ending timestamp (in seconds) for retrieving analysis data. Must be a valid Unix timestamp and greater than begin_time. |
|
|
| Yes | Indicators define the metrics you can query and are categorized into Custom Indicators and UTM Indicators.
|
|
|
| No | Time zone adjustment for analysis, in hours. |
|
|
| No | Page number for pagination . |
|
|
| No | Maximum number of records per page. Defaults to 20 and cannot exceed 200. |
|
|
| No | Field for sorting the data, chosen from the |
|
|
| No | Sorting direction: |
|
|
| No | Time granularity for aggregation: |
|
|
| No | Dimensions for the query:
| ["utm_source", "utm_campaign"] |
|
| No | Filters for analysis, such as UTM source or country code. |
|
Response Explanation
Public Response Parameters
Success Response
| Field | Type | Description | Example |
|---|---|---|---|
count | int | Total number of records in the query. | 2 |
data | array | Array of analytical data records. | See data structure below |
data.date_time | string | Timestamp of the record (ISO 8601). | "2023-05-16T16:00:00Z" |
data.country_abbr | string | Country abbreviation or region name. | "shenzhen" |
data.country_code | string | ISO country code. | "CN" |
data.utm_source | string | UTM source used for campaign tracking. | "-" |
data.pv | int | Page views. | 0 |
data.uv | int | Unique visitors. | 0 |
data.add_cart_uv | int | Number of unique visitors who added items to the cart. | 0 |
data.add_cart_qty | int | Total quantity of items added to the cart. | 0 |
data.begin_checkout_pv | int | Page views for the checkout page. | 0 |
data.begin_checkout_uv | int | Unique visitors who began the checkout process. | 0 |
data.orders | int | Number of orders placed. | 1 |
data.sales | float | Total sales amount. | 10.6 |
data.conversion_rate | float | Conversion rate calculated as orders / uv. | 0.5 |
Error Response
Error responses in the API can be represented using two different fields: errors and error. Both fields provide details about issues encountered during request processing. Below is an explanation of the fields with their respective examples and descriptions.
| Field | Type | Example | Description |
|---|---|---|---|
error | String | "page not found" | Indicates an error encountered during the process |
Error Detail
| Status Code | Message | Possible Reason | Example Response |
|---|---|---|---|
| 400 | Bad Request | Invalid input format or request structure, such as missing required fields or exceeding limits. | Bad Request |
| Unauthorized | Missing or invalid authentication credentials. | Unauthorized | |
| 404 | Not found | Script's ID is empty or not provided | "record not found" |
| 422 | Unprocessable Entity | page is less than or equal to 0. | page can't less or equals 0 |
limit is less than or equal to 0, or exceeds the maximum value (200). | limit can't less or equals 0, limit max 200 | ||
dt_by value is invalid (not in supported values). | dt_by not support | ||
dimension contains unsupported fields, or mixes custom and UTM dimensions. | not support dimension or not support use custom together with utm | ||
indicator contains unsupported values for the selected dimension type. | indicator not support when request is custom dimension, indicator not support when request is utm dimension | ||
sort_by is not in the list of specified indicator values. | sort_by need choose in the indicator | ||
sort_direction value is invalid (not asc or desc). | sort_direction not support | ||
filters contain invalid key-value pairs (e.g., missing = or empty key/value). | filter country_code illegal |