# Store Ad Campaign Schedule API Endpoint ## API Information - **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 ```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/detail/ad-schedule", "params": { "id": "c2d5b2547218a", "type": 1, "time_start": 1704067200, "time_end": 1706745599 } }' ``` ## Response Parameters ### Response Body Structure ```json { "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 | ### Response Result Information Fields | 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 ### TikTok Platform Data Example (type=1) ```json { "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 } ``` ### Facebook Platform Data Example (type=2) ```json { "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) ```json { "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 ### 1. Platform Type Description - **type=1 (TikTok Platform)**: - Count daily ad campaign volume for the store on TikTok platform - Data source: TikTok ad video data - **type=2 (Facebook Platform)**: - Count daily ad campaign volume for the store on Facebook platform - Data source: Facebook ad data ### 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