Pipispy API中文

Data usage rules: 1. Obtaining a data result consumes 1 data. Obtaining more detailed information about a data result does not consume data. 2. Ad Tracker: Each monitoring session costs $1/month. Each monitoring session is valid for one month and automatically expires after one month. Deleting a monitoring session does not restore the monitoring session, so please delete with caution. Monitoring sessions can be accessed at any time and are unlimited.

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

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

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)

{
  "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)

{
  "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

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