get https://{shopdomain}.myshoplaza.com/openapi/2022-01/data/analysis
Requires
read_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 |
|---|---|---|---|---|
begin_time | int32 | Yes | The starting timestamp (in seconds) for retrieving analysis data. Must be a valid Unix timestamp and less than end_time. Logic | 1666512000 |
end_time | int32 | Yes | The ending timestamp (in seconds) for retrieving analysis data. Must be a valid Unix timestamp and greater than begin_time. | 1682323199 |
indicator | array<string> | Yes | Indicators define the metrics you can query and are categorized into Custom Indicators and UTM Indicators. Custom indicators are valid for custom dimensions： pv,uv,add_cart_uv, add_cart_qty,add_payment_info_uv,begin_checkout_pv,begin_checkout_uv,orders, sales,conversion_rateUTM indicators are valid for UTM dimensions pv,uv,add_cart_uv,begin_checkout_pv,begin_checkout_uv,orders, sales | ["pv", "sales"] |
tz | float | No | Time zone adjustment for analysis, in hours. Notice: Values outside the range -12 to 14 might lead to unexpected results in time-based calculations. | 8 |
page | int32 | No | Page number for pagination . Defaults to 1. Value must be greater than 0. | 1 |
limit | int32 | No | Maximum number of records per page. Defaults to 20 and cannot exceed 200. | 50 |
sort_by | string | No | Field for sorting the data, chosen from the indicator fields. | sales |
sort_direction | string | No | Sorting direction: asc (ascending) or desc (descending). | desc |
dt_by | string | No | Time granularity for aggregation: dt_by_hour, dt_by_day. | dt_by_day |
dimension | array<string> | No | Dimensions for the query: - Valid custom dimensions include country_code. - Valid UTM dimensions include utm_source, utm_medium, utm_term, utm_campaign, utm_content. Notice: Mixing custom dimensions (e.g., country_code) with UTM-based dimensions will cause validation failure. | ["utm_source", "utm_campaign"] |
filters | array<string> | No | Filters for analysis, such as UTM source or country code. | ["utm_source=google", "country_code=CN"] |
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 |