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

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

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

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

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