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 New Rank List API

API Information

  • API Name: Get Ad Product New Rank List
  • Request Method: POST
  • API URL: /open-api/v1/data
  • Interface URI path: /v3/api/open/rank/ad-product-new/list
  • Description: Get ad product new 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-new/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
found_time Double Yes Discovery time range: 0-default, 1-Last 3 days , 2-Last 7 days, 3-Last 1 month, 4-Last 3 months, 5-Last 6 months, 6-all
page_size Integer Yes Page size, number of records per page for pagination query
sort_key String Yes Sort field: count_growth-Likes, growth_rate-Growth Rate, video_count-Ads
sort_type String Yes Sort type: desc-descending, asc-ascending
type Integer Yes Time type: 0-default, 1-Last 24 hours, 2-Last 3 days, 3-Last 7 days
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-new/list",
    "params": {
      "current_page": 1,
      "found_time": 1,
      "page_size": 20,
      "sort_key": "count_growth",
      "sort_type": "desc",
      "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 number
timestamp String/Null Timestamp
sign String/Null Signature information
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 Example
id String Product unique identifier ID "6868c8124423dd56cf7ea285"
image String Product main image URL "https://cdn-product.pipispy.com/pimg_5207a34434df898bdaca.png"
title String Product title "Baby Hands & Feet Casting Kit"
currency String Product price currency type, may be empty "USD", "BRL", "AUD", "EUR", "GBP", "JPY", ""
price Double Product price 120.0, 137.9, 119.0
usd_price Double Product USD price, may be empty 120.0, 25.26, 77.78
min_cpm Double Minimum CPM (cost per thousand impressions), may be empty 4712.15, 14031.55, 8670.1
max_cpm Double Maximum CPM (cost per thousand impressions), may be empty 18890.6, 56126.19, 34680.38
count_growth Long Data growth amount (play count growth) 183674, 114088, 110683
video_count Long Video count 34, 8, 15
growth_rate Double Growth rate (percentage value) 16.9425, 1.8143, 611.5083
is_collection Boolean Whether already collected false
platform String Platform identifier "shopify"

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": "6868c8124423dd56cf7ea285",
        "image": "https://cdn-product.pipispy.com/pimg_5207a34434df898bdaca.png",
        "title": "Baby Hands & Feet Casting Kit",
        "currency": "USD",
        "price": 120.0,
        "platform": "shopify",
        "usd_price": 120.0,
        "min_cpm": 4712.15,
        "max_cpm": 18890.6,
        "count_growth": 183674,
        "video_count": 34,
        "growth_rate": 16.9425,
        "is_collection": false
      },
      {
        "id": "68656c2a9a22ed62395b6d9f",
        "image": "https://cdn-product.pipispy.com/pimg_8a1a4534450f949cd18c.png",
        "title": "Kit Caterpillar - Bota Masculina em Couro Legítimo e Palmilha Ortopédica + Brindes Exclusivos",
        "currency": "BRL",
        "price": 137.9,
        "platform": "shopify",
        "usd_price": 25.26,
        "min_cpm": 14031.55,
        "max_cpm": 56126.19,
        "count_growth": 114088,
        "video_count": 8,
        "growth_rate": 1.8143,
        "is_collection": false
      }
    ],
    "page": {
      "total_count": 37834,
      "page_count": 1892,
      "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 percentage values
  7. Some fields may be empty (such as currency, usd_price, min_cpm, max_cpm)
  8. Platform identifier currently mainly returns "shopify"
  9. Image URLs use CDN domain cdn-product.pipispy.com
  10. Product IDs are in 24-bit MongoDB ObjectId format