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.

Ad Product Rank List API

API Information

  • API Name: Get Ad Product Rank List
  • Request Method: POST
  • API URL: /open-api/v1/data
  • Interface URI path: /v3/api/open/rank/ad-product/list
  • Description: Get ad product rank list information based on filter conditions with pagination support
  • Pricing: Retrieving one data result consumes 1 credit

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 Interface URI path "/v3/api/open/rank/ad-product/list" Yes
params object Interface parameter object See parameter list below Yes

Request Body Parameters (params object)

Parameter Name Type Required Description
current_page Integer Yes Current page number, pagination query current page, starting from 1
page_size Integer Yes Page size, number of records per page for pagination query
sort_key String Yes Sort field: count_growth-play count growth, growth_rate-growth rate, video_count-ad count
sort_type String Yes Sort type: desc-descending, asc-ascending
time Integer Yes The midnight time starting from the date. If it is a day, it is reported as midnight of the current day. If it is a week, it is reported as midnight of the current week. If it is a month, it is reported as midnight of the current month
type Integer Yes Ranking type: 1-Daily Ranking, 2-Weekly Ranking, 3-Monthly Ranking
count_growth_max Double No Likes, Data growth maximum value (play count growth), used to filter products with growth not exceeding specified value
count_growth_min Double No Likes, Data growth minimum value (play count growth), used to filter products with growth not below specified value
growth_rate_max Double No Growth Rate, Data growth rate maximum value, used to filter products with growth rate not exceeding specified value
growth_rate_min Double No Growth Rate, Data growth rate minimum value, used to filter products with growth rate not below specified value
plat_type Integer No Platform type: 0-all platforms, 1-TikTok, 2-Facebook
region String No Country/Region, Target regions, multiple separated by commas
shop_type String No Ecom Platform, e.g "magento", "shopify", "shoplazza", "shopline", "shopyy", "squarespace", "wix", "woocommerce"

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/rank/ad-product/list",
    "params": {
      "current_page": 1,
      "page_size": 20,
      "sort_key": "count_growth",
      "sort_type": "desc",
      "time": 1,
      "type": 1,
      "count_growth_min": 1000,
      "count_growth_max": 1000000,
      "growth_rate_min": 0.1,
      "growth_rate_max": 1.0,
      "plat_type": 1,
      "region": "US,CA,GB"
    }
  }'

Response Parameters

Response Body Structure

{
  "code": 200,
  "message": "success",
  "data": {
    "data": [],
    "page": {}
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 20,
  "success": true,
  "fail": false
}

Response Field Description

Field Name Type Description
code Integer Response status code, 200 indicates success
message String Response message
data Object Response data
data.data Array Product rank list
data.page Object Pagination information
version String API version
timestamp String Response timestamp (nullable)
sign String Response signature (nullable)
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

Product Rank Information Fields

Field Name Type Description
id String Product unique identifier ID
image String Product main image URL
title String Product title
currency String Product price currency type
price Double Product price
usd_price Double Product USD price
min_cpm Double Minimum CPM (cost per thousand impressions), nullable
max_cpm Double Maximum CPM (cost per thousand impressions), nullable
count_growth Long Data growth amount (play count growth)
video_count Long Video count
growth_rate Double Growth rate
is_collection Boolean Whether already collected
platform String Platform identifier (e.g., "shopify", "shopline")

Pagination Information Fields

Field Name Type Description
total_count Long Total number of records
page_count Long Total number of pages
current_page Long Current page number
page_size Long Records per page
is_next Boolean Whether has next page

Response Example

{
  "code": 200,
  "message": "success",
  "data": {
    "data": [
      {
        "id": "67a2d72695f8665640581129",
        "image": "https://cdn-product.pipispy.com/pimg_7560a46afc0d626f9f70.png",
        "title": "Hermès Avalon Throw Blanket",
        "currency": "USD",
        "price": 149.99,
        "platform": "shopify",
        "usd_price": 149.99,
        "count_growth": 175621,
        "video_count": 14,
        "growth_rate": 0.2957,
        "is_collection": false
      },
      {
        "id": "674bf2ec6b331c3c04ad0a9a",
        "image": "https://cdn-product.pipispy.com/pimg_a15c12f7d699c40dc6d5.jpg",
        "title": "Compression Backpack",
        "currency": "INR",
        "price": 9499.0,
        "platform": "shopify",
        "usd_price": 110.8,
        "count_growth": 44047,
        "video_count": 6,
        "growth_rate": 3.0072,
        "is_collection": false
      },
      {
        "id": "65c024af7ffbbd340830304e",
        "image": "https://cdn-product.pipispy.com/pimg_603e433b11adfc4d1107.jpg",
        "title": "Furry Dino Bear | Handmade Jointed Teddy Bear Gift-Getahug",
        "currency": "USD",
        "price": 12.98,
        "platform": "shopline",
        "usd_price": 12.98,
        "min_cpm": 864.23,
        "max_cpm": 3467.1,
        "count_growth": 33316,
        "video_count": 5,
        "growth_rate": 0.011,
        "is_collection": false
      }
    ],
    "page": {
      "total_count": 101654,
      "page_count": 5083,
      "current_page": 1,
      "page_size": 20,
      "is_next": true
    }
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 20,
  "success": true,
  "fail": false
}

Error Code Description

Error Code Description
200 Success
400 Request parameter error
500 Server internal error

Notes

  1. Page number parameters start from 1
  2. Sort fields support multiple options: count_growth, growth_rate, video_count
  3. Time range filtering supports multiple predefined time periods
  4. Platform filtering supports TikTok and Facebook platforms
  5. Region parameters support multiple regions separated by commas
  6. Growth rate is calculated as a percentage value
  7. min_cpm and max_cpm fields may be null, indicating no CPM data available for the product
  8. platform field shows specific e-commerce platform names such as "shopify", "shopline", etc.
  9. The version field in the response indicates the API version, timestamp and sign fields are currently null
  10. success and fail fields are used to indicate request processing status