Store Ad Campaign Schedule API Endpoint
- API Name: Store Ad Campaign Schedule API Endpoint
- Request Method: GET
- API Address:
/open-api/v1/data
- API Path:
/v3/api/open/store/detail/ad-schedule
- API Description:
- Query ad campaign schedule data for a specified store on different platforms (TikTok/Facebook)
- Count daily ad campaign volume by date
- Support filtering by time range to understand the store's ad campaign pace
- Help analyze the store's ad campaign strategy and active cycles
- Pricing:
Free
Request Headers:
- Content-Type: application/json
- Accept: application/json
Request Parameters
Request Structure
| Parameter Name |
Type |
Description |
Example |
Required |
Default Value |
| key |
string |
User's external API request key |
"your_api_key_here" |
Yes |
|
| uri |
string |
API path |
"/v3/api/open/store/detail/ad-schedule" |
Yes |
|
| params |
object |
API 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 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 provided |
| time_end |
long |
false |
End time, timestamp (seconds), no end time limit if not provided |
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/detail/ad-schedule",
"params": {
"id": "c2d5b2547218a",
"type": 1,
"time_start": 1704067200,
"time_end": 1706745599
}
}'
Response Parameters
Response Body Structure
{
"code": 200,
"message": "success",
"data": {
"data": [
{
"day": 1704067200,
"ad_count": 150
},
{
"day": 1704153600,
"ad_count": 165
},
{
"day": 1704240000,
"ad_count": 142
}
]
},
"version": "v1",
"timestamp": null,
"sign": null,
"remaining_credits": 9980,
"consumed_credits": 0,
"fail": false,
"success": true
}
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 |
| Field Name |
Type |
Description |
| data |
Array[Object] |
Daily campaign data list |
data Array Element Structure (Daily Campaign Data)
| Field Name |
Type |
Description |
| day |
Long |
Statistics date, timestamp (seconds) |
| ad_count |
Long |
Ad campaign volume for that day |
Note:
- Data is sorted in ascending order by date, from earliest to latest
- Only returns date data where ad count is greater than 0
- Depending on the type parameter, statistics are for different platforms' ad counts
Response Example
{
"code": 200,
"message": "success",
"data": {
"data": [
{
"day": 1704067200,
"ad_count": 150
},
{
"day": 1704153600,
"ad_count": 165
},
{
"day": 1704240000,
"ad_count": 142
},
{
"day": 1704326400,
"ad_count": 178
},
{
"day": 1704412800,
"ad_count": 155
},
{
"day": 1704499200,
"ad_count": 188
},
{
"day": 1704585600,
"ad_count": 195
},
{
"day": 1704672000,
"ad_count": 210
},
{
"day": 1704758400,
"ad_count": 185
},
{
"day": 1704844800,
"ad_count": 172
}
]
},
"version": "v1",
"timestamp": null,
"sign": null,
"remaining_credits": 9980,
"consumed_credits": 0,
"fail": false,
"success": true
}
{
"code": 200,
"message": "success",
"data": {
"data": [
{
"day": 1704067200,
"ad_count": 85
},
{
"day": 1704153600,
"ad_count": 92
},
{
"day": 1704240000,
"ad_count": 78
},
{
"day": 1704326400,
"ad_count": 95
},
{
"day": 1704412800,
"ad_count": 88
},
{
"day": 1704499200,
"ad_count": 102
},
{
"day": 1704585600,
"ad_count": 110
},
{
"day": 1704672000,
"ad_count": 98
},
{
"day": 1704758400,
"ad_count": 105
},
{
"day": 1704844800,
"ad_count": 92
}
]
},
"version": "v1",
"timestamp": null,
"sign": null,
"remaining_credits": 9980,
"consumed_credits": 0,
"fail": false,
"success": true
}
Unlimited Time Range Example (without time_start and time_end)
{
"code": 200,
"message": "success",
"data": {
"data": [
{
"day": 1672531200,
"ad_count": 45
},
{
"day": 1672617600,
"ad_count": 52
},
{
"day": 1672704000,
"ad_count": 48
},
...
{
"day": 1706745600,
"ad_count": 210
}
]
},
"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
2. Time Range
- Both time_start and time_end are optional parameters:
- If no time parameters are provided, returns all historical campaign data for the store
- If only time_start is provided, returns campaign data from that time point to the latest
- If only time_end is provided, returns campaign data from the earliest to that time point
- If both are provided, returns campaign data within that time range
- Timestamp unit is seconds
3. Data Sorting
- Data is sorted in ascending order by statistics date (day field)
- From earliest date to latest date
- Convenient for observing trends in campaign evolution over time
4. Data Filtering
- Only returns dates where ad count is greater than 0
- If there are no ad campaigns on a certain day, that date will not appear in the results
- Ensures all returned data is valid campaign data