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 Meta Ads Library Delivery Trend Analysis API

API Information

  • API Name: Store Ad Meta Ads Library Delivery Trend Analysis API
  • Request Method: POST
  • API Endpoint: /open-api/v1/data
  • API Path: /v3/api/open/ppspy/pp-stores/analysis/ad-trend
  • API Description: Retrieve ad delivery trend data for a specified store in the Meta Ads Library, including historical trends of active ad count, total ad count, and new ad count
  • Pricing: Free

Request Headers:

  • Content-Type: application/json
  • Accept: application/json

Request Parameters

Request Structure

Parameter Type Description Example Required Default
key string User's external API request key "your_api_key_here" Yes
uri string API path "/v3/api/open/ppspy/pp-stores/analysis/ad-trend" Yes
params object API input parameter object See parameter list Yes

Request Body Parameters (params object)

Parameter Type Required Description
id String Yes Store unique identifier ID, a 13-character string (e.g., c2d5b2547218a), corresponds to the store_id field in the store ranking list API response
start_time Long Yes Query start time, Unix timestamp (seconds). Used to specify the start date for statistics
end_time Long Yes Query end time, Unix timestamp (seconds). Used to specify the end date for statistics. Recommended time range should not exceed 90 days for optimal performance

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/ppspy/pp-stores/analysis/ad-trend",
    "params": {
        "id": "c2d5b2547218a",
        "start_time": 1700000000,
        "end_time": 1707776000
    }
  }'

Response Parameters

Response Body Structure

{
  "code": 200,
  "message": "success",
  "data": {
    "active_ad_count_history": [],
    "ad_count_history": [],
    "ad_started_history": [],
    "is_logged_in": false
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 0,
  "success": true,
  "fail": false
}

Response Field Description

Field 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

Ad Trend Analysis Data Fields (data.data)

Field Type Description
active_ad_count_history Array Historical data of active ad count, records the number of ads actively running each day. Active ads are ads still in delivery status on that day
ad_count_history Array Historical data of total ad count, records the cumulative total number of ads each day. This is a cumulative value including all historical ads (active + stopped)
ad_started_history Array Historical data of new ad count, records the number of ads that started running each day. Indicates new ads that went live on that day
is_logged_in Boolean Whether the user is logged in, used to identify data permission status

Historical Data Item Fields (HistoryItem)

Each element in the active_ad_count_history, ad_count_history, and ad_started_history arrays contains the following fields:

Field Type Description
date String Statistical date, format is yyyy-MM-dd (e.g., 2024-01-15)
count Long Count value for that date. Depending on the array, it represents: active ad count, total ad count, or new ad count

Response Example

{
  "code": 200,
  "message": "success",
  "data": {
    "active_ad_count_history": [
      {
        "date": "2024-01-01",
        "count": 125
      },
      {
        "date": "2024-01-02",
        "count": 138
      },
      {
        "date": "2024-01-03",
        "count": 145
      }
    ],
    "ad_count_history": [
      {
        "date": "2024-01-01",
        "count": 1500
      },
      {
        "date": "2024-01-02",
        "count": 1523
      },
      {
        "date": "2024-01-03",
        "count": 1548
      }
    ],
    "ad_started_history": [
      {
        "date": "2024-01-01",
        "count": 15
      },
      {
        "date": "2024-01-02",
        "count": 23
      },
      {
        "date": "2024-01-03",
        "count": 25
      }
    ],
    "is_logged_in": false
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 0,
  "success": true,
  "fail": false
}

Error Code Description

Error Code Description
200 Success
400 Invalid request parameters
401 Unauthorized
403 Insufficient permissions
500 Internal server error