Store Play Cost Detail Query API Endpoint
API Endpoint Information
- API Endpoint Name: Store Play Cost Detail Query API Endpoint
- Request Method: GET
- API Endpoint Address:
/open-api/v1/data - API Endpoint Path:
/v3/api/open/store/play-cost/detail - API Endpoint Description:
- Query daily play cost detail data for a specified store on different platforms (TikTok/Facebook)
- Supports filtering by time range to get the store's daily ad delivery performance data
- Includes ad count, play count, CPM cost, engagement data (likes, comments, shares) and other metrics
- Pricing:
Free
Request Headers:
- Content-Type: application/json
- Accept: application/json
Request Parameters
Request Structure
| Parameter Name | Type | Description | Example | Required | Default |
|---|---|---|---|---|---|
key | string | User's external API request key | "your_api_key_here" | Yes | |
uri | string | API Endpoint path | "/v3/api/open/store/play-cost/detail" | Yes | |
params | object | API Endpoint input parameter object | See parameter list | Yes |
Request Body Parameters (params object)
| Parameter Name | Type | Required | Description |
|---|---|---|---|
id | string | true | Store ID is a 13-character string (e.g., c2d5b2547218a), corresponding to the store_id field in the store ranking list API endpoint response |
type | integer | false | Platform type: 1-TikTok platform, 2-Facebook platform, default is 1 |
time_start | long | false | Start time, timestamp (seconds), no start time limit if not passed |
time_end | long | false | End time, timestamp (seconds), no end time limit if not passed |
current_page | integer | false | Current page number, default is 1 |
page_size | integer | false | Number of records per page, default is 10 |
Request Example
curl -X POST "https://www.pipispy.com/open-api/v1/data" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"key": "your_api_key_here",
"uri": "/v3/api/open/store/play-cost/detail",
"params": {
"id": "c2d5b2547218a",
"type": 1,
"time_start": 1704067200,
"time_end": 1706745599,
"current_page": 1,
"page_size": 10
}
}'
Response Parameters
Response Body Structure
{
"code": 200,
"message": "success",
"data": {
"data": [
{
"max_cpm": 12.6,
"digg_count": 8,
"ad_count": 1,
"comment": 0,
"share": 0,
"play_count": 2271,
"day": 1706716800,
"min_cpm": 3.14
},
{
"max_cpm": 17.56,
"digg_count": 2,
"ad_count": 2,
"comment": 0,
"share": 0,
"play_count": 3165,
"day": 1706630400,
"min_cpm": 4.38
},
{
"max_cpm": 21.28,
"digg_count": 6,
"ad_count": 2,
"comment": 0,
"share": 0,
"play_count": 3836,
"day": 1706544000,
"min_cpm": 5.31
},
{
"max_cpm": 7.93,
"digg_count": 4,
"ad_count": 1,
"comment": 0,
"share": 0,
"play_count": 1429,
"day": 1706284800,
"min_cpm": 1.98
},
{
"max_cpm": 30.8,
"digg_count": 21,
"ad_count": 3,
"comment": 0,
"share": 1,
"play_count": 5552,
"day": 1706198400,
"min_cpm": 7.69
},
{
"max_cpm": 54.11,
"digg_count": 20,
"ad_count": 3,
"comment": 1,
"share": 0,
"play_count": 9754,
"day": 1706112000,
"min_cpm": 13.5
},
{
"max_cpm": 27.51,
"digg_count": 4,
"ad_count": 3,
"comment": 0,
"share": 0,
"play_count": 4959,
"day": 1706025600,
"min_cpm": 6.86
},
{
"max_cpm": 46.78,
"digg_count": 24,
"ad_count": 3,
"comment": 0,
"share": 2,
"play_count": 8434,
"day": 1705939200,
"min_cpm": 11.68
},
{
"max_cpm": 85.55,
"digg_count": 54,
"ad_count": 3,
"comment": 4,
"share": 0,
"play_count": 15423,
"day": 1705852800,
"min_cpm": 21.35
},
{
"max_cpm": 48.53,
"digg_count": 31,
"ad_count": 3,
"comment": 0,
"share": 2,
"play_count": 8748,
"day": 1705766400,
"min_cpm": 12.11
}
],
"page": {
"total_count": 23,
"current_page": 1,
"page_count": 3,
"page_size": 10
}
},
"version": "v1",
"timestamp": null,
"sign": null,
"remaining_credits": 9980,
"consumed_credits": 0,
"success": true,
"fail": false
}
Response Field Descriptions
| Field Name | Type | Description |
|---|---|---|
code | Integer | Response status code, 200 means success |
message | String | Response message |
data | Object | Response data |
version | String | API version |
timestamp | String | Response timestamp |
sign | String | Response signature |
remaining_credits | Long | Current remaining available credits after this request |
consumed_credits | Long | Credits consumed by this request |
success | Boolean | Whether the request was successful |
fail | Boolean | Whether the request failed |
Response Result Information Fields
| Field Name | Type | Description |
|---|---|---|
data | Array[Object] | Daily data list |
page | Object | Pagination information |
data Array Element Structure (Daily Data)
| Field Name | Type | Description |
|---|---|---|
day | Long | Statistics date, timestamp (seconds) |
ad_count | Long | Number of ads for that day |
play_count | Long | Number of plays for that day (TikTok platform only has this field, returned when type=1) |
min_cpm | Double | Minimum CPM cost for that day (TikTok platform only has this field, returned when type=1) |
max_cpm | Double | Maximum CPM cost for that day (TikTok platform only has this field, returned when type=1) |
digg_count | Long | Number of likes for that day |
comment | Long | Number of comments for that day |
share | Long | Number of shares for that day |
Note:
- When type=1 (TikTok platform), all fields are returned
- When type=2 (Facebook platform), play_count, min_cpm, max_cpm fields are null or not returned
page Object Structure
| Field Name | Type | Description |
|---|---|---|
current_page | Integer | Current page number |
page_size | Integer | Number of records per page |
total | Long | Total number of records |
Response Example
TikTok Platform Data Example (type=1)
{
"code": 200,
"message": "success",
"data": {
"data": [
{
"day": 1706745600,
"ad_count": 150,
"play_count": 1250000,
"min_cpm": 2.5,
"max_cpm": 15.8,
"digg_count": 35000,
"comment": 2500,
"share": 1800
},
{
"day": 1706659200,
"ad_count": 145,
"play_count": 1180000,
"min_cpm": 2.3,
"max_cpm": 14.5,
"digg_count": 32000,
"comment": 2300,
"share": 1650
},
{
"day": 1706572800,
"ad_count": 138,
"play_count": 1050000,
"min_cpm": 2.1,
"max_cpm": 13.2,
"digg_count": 28000,
"comment": 2100,
"share": 1500
}
],
"page": {
"current_page": 1,
"page_size": 10,
"total": 60
}
},
"version": "v1",
"timestamp": null,
"sign": null,
"remaining_credits": 9980,
"consumed_credits": 0,
"fail": false,
"success": true
}
Facebook Platform Data Example (type=2)
{
"code": 200,
"message": "success",
"data": {
"data": [
{
"day": 1706745600,
"ad_count": 85,
"play_count": 0,
"min_cpm": null,
"max_cpm": null,
"digg_count": 12000,
"comment": 850,
"share": 620
},
{
"day": 1706659200,
"ad_count": 80,
"play_count": 0,
"min_cpm": null,
"max_cpm": null,
"digg_count": 11500,
"comment": 800,
"share": 580
}
],
"page": {
"current_page": 1,
"page_size": 10,
"total": 45
}
},
"version": "v1",
"timestamp": null,
"sign": null,
"remaining_credits": 9980,
"consumed_credits": 0,
"fail": false,
"success": true
}
Error Code Descriptions
| Error Code | Description |
|---|---|
200 | Success |
400 | Request parameter error |
500 | Internal server error |
Usage Instructions
-
Platform Type Description:
- type=1 queries TikTok platform data, returns complete data including play count and CPM cost
- type=2 queries Facebook platform data, returns engagement data but does not include play count and CPM cost
-
Time Range:
- time_start and time_end are both optional parameters
- If time parameters are not passed, all historical data for the store is returned
- Timestamp unit is seconds
-
Data Sorting:
- Data is sorted by statistics date (day field) in descending order, with the most recent dates first
-
Pagination:
- Supports pagination queries, controlled by current_page and page_size
- Default is 10 records per page