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.

Adspy List Interface

Interface Information

  • Interface Name: Get Adspy List
  • Request Method: POST
  • Interface Address: /open-api/v1/data
  • Interface Path: /v3/api/open/adspy/list
  • Interface Description: Get Adspy 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 Type Description Example Required Default
key string User's external API request key "your_api_key_here" Yes
uri string Endpoint path "/v3/api/open/adspy/list" Yes
params object Request parameters object See parameter list Yes

Parameter List (params object)

Required Parameters

Parameter Type Description Example Required Default
current_page number Current page number (required) 1 Yes
page_size number Number per page (required) 10 Yes

Optional Parameters (Alphabetical Order)

Parameter Type Description Example Required Default
ad_cost_max number Maximum ad spend 1000.0 No
ad_cost_min number Minimum ad spend 10.0 No
ad_duration_max number Maximum ad duration (seconds) 60 No
ad_duration_min number Minimum ad duration (seconds) 10 No
ad_language string array Ad language list, supports "other" for other languages ["en"] No
ad_state number Ad delivery status filter. TimeStampUtils.getToday() is the Unix timestamp in seconds for 00:00:00 of the current date in the Asia/Shanghai time zone. 1 means Active, with the filter condition modify_time >= TimeStampUtils.getToday(), indicating the ad still has delivery-related updates or active records after 00:00:00 of the current Asia/Shanghai date. 0 means Stopped, with the filter condition modify_time <= TimeStampUtils.getToday(), indicating the latest delivery-related update time is not later than 00:00:00 of the current Asia/Shanghai date. When this parameter is not empty, last_time_start and last_time_end are ignored and no longer participate in the query condition calculation. 1=Active, 0=Stopped No
after string array Cursor pagination parameter ["cursor1","cursor2"] No
age string array Age range list, format like "18-24" ["25-35"] No
ai_analysis_tags string array AI analysis tag list, query using script analysis tags ["tag1"] No
ai_category string array AI category list, using AI categories on toolify (not yet used) ["cat1"] No
app_category string array App category/game category ["fashion","beauty"] No
app_dev_id string APP developer ID "dev123" No
app_id string APP ID "app123" No
app_system string APP platform: ios/android, supports comma-separated multiple platforms "ios" No
app_type string APP type "ios" No
aspect_ratio string array Resolution list: 640×360, 360×640, 854×480, 480×854, 720×720, 1080×1080, 1280×720, 720×1280, 1920×1080, 1080×1920, 2560×1440, 1440×2560 ["720×1280"] No
button string array CTA button, button type list ["Shop now"] No
clarity string array Video quality: SD, HD, Full HD, UHD/4K, 8K ["HD"] No
comment_count_max number Maximum comment count 500 No
comment_count_min number Minimum comment count 5 No
create_time_end number Creation time end (timestamp) 1709827199 No
create_time_start number Creation time start (timestamp) 1709654400 No
data_type number array Data type list: 1-Hot Product Follow-up, 2-Mini Shop (TTS) Ad, 3-E-commerce, 4-Spark Ads, 5-Game, 6-App, 7-AI, 8-Short Drama [1,2] No
digg_count_max number Maximum like count 1000 No
digg_count_min number Minimum like count 10 No
digg_rate_max number Maximum like rate 0.1 No
digg_rate_min number Minimum like rate 0.01 No
download_count_max number Maximum APP download count 1000 No
download_count_min number Minimum APP download count 10 No
estimated_conversion_max number Maximum estimated conversion 0.1 No
estimated_conversion_min number Minimum estimated conversion 0.01 No
exclude_word object array Exclude word list, see Keyword Search Format Specification [] No
extend_keywords object array Extended keyword list, see Keyword Search Format Specification [] No
first_time_end number First found time end (timestamp) 1709827199 No
first_time_start number First found time start (timestamp) 1709654400 No
formate_type number array Ad format: 1-Video, 2-Image, 3-Carousel [1,2] No
hot_value_max number Maximum engagement count 1000 No
hot_value_min number Minimum engagement count 10 No
interest string Interest feature "gaming" No
is_and boolean Whether multi-word query (AND/OR logic), defaults to false (OR logic) false No false
is_ad_fake boolean Non-brand ad (non-Spark Ads) false No
is_app boolean Has APP product true No
is_participle boolean Whether to use word segmentation, defaults to true true No true
is_product boolean Has ad product true No
is_real string Whether real person ad: no-AI, yes-Real person, empty defaults to search all "yes" No
is_recommend number Whether recommended content 0 No
is_redirect boolean Has redirect link false No
is_tiktok_shop boolean Has mini shop product false No
is_url number URL status: 0-No landing page link, 1-Has landing page link 1 No
last_time_end number Last found time end (timestamp) 1711036799 No
last_time_start number Last found time start (timestamp) 1710864000 No
monthly_income_max number Maximum APP monthly revenue (USD) 100000.0 No
monthly_income_min number Minimum APP monthly revenue (USD) 1000.0 No
monthly_install_max number Maximum APP monthly installs 100000 No
monthly_install_min number Minimum APP monthly installs 1000 No
play_count_max number Maximum play count 10000 No
play_count_min number Minimum play count 100 No
plat_type number Platform type: 1-TikTok, 2-Facebook 1 No
popular_person_id string Influencer ID "person123" No
product_category_id string array Category, same as ad product page categories ["cat1"] No
product_id string Product ID "prod123" No
put_day_max number Maximum delivery days 30 No
put_day_min number Minimum delivery days 1 No
reaction_anger_max number Facebook reaction "Anger" maximum 1000 No
reaction_anger_min number Facebook reaction "Anger" minimum 10 No
reaction_care_max number Facebook reaction "Care" maximum 1000 No
reaction_care_min number Facebook reaction "Care" minimum 10 No
reaction_haha_max number Facebook reaction "Haha" maximum 1000 No
reaction_haha_min number Facebook reaction "Haha" minimum 10 No
reaction_love_max number Facebook reaction "Love" maximum 1000 No
reaction_love_min number Facebook reaction "Love" minimum 10 No
reaction_sad_max number Facebook reaction "Sad" maximum 1000 No
reaction_sad_min number Facebook reaction "Sad" minimum 10 No
reaction_wow_max number Facebook reaction "Wow" maximum 1000 No
reaction_wow_min number Facebook reaction "Wow" minimum 10 No
region string array Country/region ["US","HK"] No
release_time_end number APP release time end (timestamp) 1709827199 No
release_time_start number APP release time start (timestamp) 1709654400 No
root_path string Advertiser "path1" No
score_max number Maximum APP rating 5.0 No
score_min number Minimum APP rating 3.0 No
search_type number Search type: 1-Ad keyword, 2-Ad copy, 3-Advertiser, 4-Landing page URL, 5-E-commerce product, 6-TikTok Shop store, 7-APP name, 8-APP developer, 9-Social media account (page name), 10-Material (script/hook/tag), 11-E-commerce store/URL, 12-TikTok Shop product 1 No
sex number array Audience-Gender: 1-Male, 2-Female [1,2] No
share_count_max number Maximum share count 500 No
share_count_min number Minimum share count 5 No
share_play_rate_max number Maximum share play rate 0.01 No
share_play_rate_min number Minimum share play rate 0.001 No
shop_type string array E-commerce system: "magento", "shopify", "shoplazza", "shopline", "shopyy", "squarespace", "wix", "woocommerce" ["ecommerce"] No
size string array Aspect ratio list: 1:1, 16:9, 4:3, 9:16, 21:9, 1:2, 3:4, 4:5, 2:1, 5:4 ["9:16"] No
skits_category string array Short drama category list (not yet used) ["cat1"] No
sort number Sort method: 1:Last found time, 2:Create time, 3:First found time, 4:Ad plays, 21:Ad spend, 14:Estimated conversion, 5:Delivery days, 6:Engagement count, 7:Like rate, 8:Share rate, 9:Like count, 10:Comment count, 11:Share count, 15:Wow, 16:Love, 17:Care, 18:Haha, 19:Sad, 20:Anger, 999:Sort by search keyword score, when paginating note after parameter should pass the last data's _score and video_id, e.g.: after:[921.20715, "2c219a83dc47a45a80ac"] 1 No 2
sort_type string Sort type "desc" No
store_id string Store unique identifier ID, a 13-character string (e.g.: c2d5b2547218a), corresponds to the store_id field in the store ranking list interface response "desc" No
tk_shop_category_id string array TikTok Shop category ID list ["cat1"] No
aigc_type string Al Creative: -1:AI Generated,0: Non-AI,1:Advertiser Labeled,2:Official Al "-1" 否

Keyword Search Format Specification

The extend_keywords and exclude_keywords parameters use JSON format:

  [
    {
      "type": 1,
      "keyword": "search keyword"
    }
  ]

Search Type (type) Explanation:

  • type:1 - Ad keyword search: the user-entered keyword will be matched against ad copy, advertiser, landing page URL, product, App, account, and creative material
  • type:2 - Ad copy: the user-entered keyword will only match against ad copy
  • type:3 - Advertiser: the user-entered keyword will search advertisers
  • type:4 - Landing page URL: the user-entered keyword will search landing page URLs and redirect links
  • type:5 - E-commerce product: the user-entered keyword will search e-commerce product names
  • type:6 - TikTok Shop store: the user-entered keyword will search TikTok Shop store names
  • type:7 - APP name: the user-entered keyword will search App application names
  • type:8 - APP developer: the user-entered keyword will search APP developer names
  • type:9 - Social media account (page name): the user-entered keyword will search social media accounts (TT account/Page ID)
  • type:10 - Creative material (script/hook/tag): the user-entered keyword will search creative material information (script/hook/tag)
  • type:11 - E-commerce store/URL: the user-entered keyword will search e-commerce store/URL
  • type:12 - TikTok Shop product: the user-entered keyword will search TikTok Shop products

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/adspy/list",
        "params": {
          "is_participle": false,
          "shop_type": [
            "magento",
            "shopify"
          ],
          "extend_keywords": [
            {
                "type": 1,
                "keyword": "shorts"
            },
            {
                "type": 2,
                "keyword": "black"
            }
          ],
          "plat_type": 1,
          "search_type": 1,
          "sort": 2,
          "sort_type": "desc",
          "current_page": 1,
          "play_count_min": 1000,
          "play_count_max": 10000,
          "create_time_start": 1761580800,
          "create_time_end": 1764172799,
          "page_size": 20
        }
  }'

Response Parameters

Response Body Structure

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

Response Field Description

Main Response Fields
Field Name Type Description
code number Response status code, 200 = success
message string Response message
data object Response data
data.data array[object] Ad data list
data.page object Pagination info
version string API version
timestamp number Response timestamp
sign string Response signature
remaining_credits number Current remaining available credits after this request
consumed_credits number Credits consumed by this request
success boolean Request success status
fail boolean Request failure status
Ad Data Fields (data) - Alphabetical Order
Field Name Type Description
id string Video ID (use this field as id to access ad details)
video_id string Video ID (use this field as id to access ad details)
ad_create_time number Ad creation time (timestamp)
ai_analysis_human_presenter string AI analysis human presenter
ai_analysis_language string AI analysis language
ai_analysis_main_hook string AI analysis main hook
ai_analysis_script string AI analysis script
ai_analysis_tags array[string] AI analysis tag list
app_dev_id string App developer ID
app_image string App image URL
app_name string App name
app_title string App title
button_text string Button text
carousel array[object] Carousel list
comment_count number Comment count
cover string Cover image URL
data_type array[number] Data type list
desc string Ad description
digg_count number Like count
digg_play_rate number Like play rate
duration number Duration (seconds)
facebook_link_angry number Facebook angry reaction count
facebook_link_care number Facebook care reaction count
facebook_link_haha number Facebook haha reaction count
facebook_link_love number Facebook love reaction count
facebook_link_sad number Facebook sad reaction count
facebook_link_wow number Facebook wow reaction count
fetch_region array[string] Fetch region list
found_time number Found time (timestamp)
had_ai_analysis boolean Whether AI analysis performed
have_tiktok_shop boolean Whether has TikTok shop
hot_value number Hot value
image string Image URL
is_collection boolean Whether collected
is_download boolean Whether downloadable
last_put_time number Last delivery time (timestamp)
min_cpa number Minimum estimated conversion, automatically calculated by PIPIADS based on big data and target region universal order CPA metrics (with margin of error)
min_cpm number Minimum ad spend, automatically calculated by PIPIADS based on big data and target region universal CPM metrics (with margin of error)
modify_time number Modification time (timestamp)
pack_url string Package URL
platform number Platform type (1:Facebook, 2:Instagram, 3:TikTok)
play_count number Play count
put_days number Delivery days
root_path_id string Advertiser ID
search_by_image_tag boolean Whether searched by image tag
share_count number Share count
share_play_rate number Share play rate
shop_type string Shop type
type number Ad type (1:video, 2:image)
video_url string Video URL
_score Number Search keyword score
aigc_label_type Number Al Creative: -1:AI Generated,0: Non-AI,1:Advertiser Labeled,2:Official Al
Field Name Type Description
aspect_ratio string Aspect ratio
body string Body content
button_text string Button text
cta_text string CTA text
cover string Cover image URL
cover_could_storage string Cover cloud storage
dimensions_type number Dimensions type
duration number Duration (seconds)
height number Height
image string Image URL
image_could_storage string Image cloud storage
link_description string Link description
link_url string Link URL
play_count number Play count
quality string Quality
resolution string Resolution
title string Title
type number Type
video_audio_user_preferred_language string Video audio user preferred language
video_url string Video URL
video_url_could_storage string Video URL cloud storage
width number Width
Pagination Info Fields (page)
Field Name Type Description
total_count number Total records
page_count number Total pages
current_page number Current page number
page_size number Page size
is_next boolean Whether has next page

Response Example

{
  "code": 200,
  "message": "success",
  "data": {
    "data": [
      {
        "search_by_image_tag": true,
        "comment_count": 2,
        "app_dev_id": "",
        "digg_play_rate": 0.0067,
        "modify_time": 1752204344,
        "pack_url": "",
        "type": 1,
        "is_collection": false,
        "platform": 1,
        "duration": 59,
        "cover": "https://cdn-video.pipispy.com/cover_7f33700d982493b5a19b158a7068af93.jpg",
        "share_play_rate": 0.0007,
        "last_put_time": 1752204344,
        "root_path_id": "61f57e4d9a301ef93d53b88a",
        "put_days": 12,
        "app_title": "I don't believe it! Your hair is oilier than mine!! #amaxy #fyp",
        "fetch_region": ["MY"],
        "ad_create_time": 1745303145,
        "play_count": 47527,
        "share_count": 32,
        "app_name": "🇲🇾Live Streamers Regina & Fiona",
        "found_time": 1749614161,
        "ad_id": "1833892866239586",
        "hot_value": 352,
        "digg_count": 318,
        "is_download": false,
        "data_type": [3],
        "button_text": "Buy now",
        "desc": "I don't believe it! Your hair is oilier than mine!! #amaxy #fyp",
        "video_id": "d9055376ae19819f4756",
        "app_image": "https://cdn-video.pipispy.com/avatar_0aa449789bac7929f216b33fde973196.jpg",
        "video_url": "https://cdn-video.pipispy.com/video_39551dc815f2501724d82a30c4a389c3.mp4",
        "ai_analysis_main_hook": "Is your hair this oily?",
        "ai_analysis_script": "Is your hair this oily? To do a test for you, I'm making such a sacrifice. This is oil, oh my, I have to make this thing. Is your hair this oily? Let me tell you, I'm only washing once. Let me see if its effect can really help us remove oil? If not, don't buy. OK, is that enough? Look at its foam, it's quite dense, and it smells nice with this fresh scent. For oily hair, you should buy this blue one, it'll help you remove oil. Then use a bit of its conditioner and apply it to the ends of your hair. Is it smooth? Oh my god, I put so much oil, and I only washed once, you see it's clean, no oil at all, no oily smell, and it's very dry and fluffy, wow it's just as it says. So if you have oily hair, I highly recommend you buy this blue amaxy, it's a gift box set with two bottles of shampoo, one bottle is 400ml, and this is a conditioner to make your hair smoother, also 400ml. If you buy this, more than a hundred bucks right? I'll give you two more 100ml bottles of shampoo, and 12 packets of shampoo, one packet is 8ml, I'm giving you nearly 300ml, one full-size is 400ml, I'm giving you almost one bottle, going right? If you also have oily hair and it's very oily if you don't wash for a day, click the link in the lower left corner of the video to buy, it really works, you'll like it.",
        "ai_analysis_tags": [
          "#shampoo",
          "#conditioner",
          "#haircare",
          "#oilyhair",
          "#amaxy",
          "#hairproduct",
          "#hair",
          "#beauty"
        ],
        "ai_analysis_language": "zh-cn",
        "ai_analysis_human_presenter": "yes",
        "had_ai_analysis": true,
        "min_cpm": 33.74,
        "min_cpa": 1.0,
        "unique_id": "hows.sis"
      }
    ],
    "page": {
      "total_count": 10000,
      "page_count": 500,
      "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
401 Unauthorized - Invalid API key
500 Internal server error