# 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 ```bash 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 ```json { "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) ```json { "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) ```json { "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 1. **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 2. **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 3. **Data Sorting**: - Data is sorted by statistics date (day field) in descending order, with the most recent dates first 4. **Pagination**: - Supports pagination queries, controlled by current_page and page_size - Default is 10 records per page