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.

Advertiser Leaderboard List API

API Information

  • API Name: Get Advertiser Leaderboard List
  • Request Method: POST
  • API Endpoint: /open-api/v1/data
  • API Path: /v3/api/open/rank/top-advertiser/list
  • API Description: Retrieve advertiser leaderboard list information based on filter conditions, supports pagination
  • 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 External API request key "your_api_key_here" Yes
uri string API path "/v3/api/open/rank/top-advertiser/list" Yes
params object API input parameters object See parameter list Yes

Request Body Parameters (params object)

Parameter Type Required Description
data_type Integer Yes Data platform type, determines which platform's advertiser data to query. Values: 0-All platforms data (TikTok + Facebook + Meta Ad Library aggregated data from three platforms), 1-TikTok platform data, 2-Facebook platform data, 3-Meta Ad Library data. This parameter affects the data source and statistical scope of other filter fields
ad_type Integer No Advertiser type, values: 0-Website, 3-E-commerce, 4-AI, 5-Short Drama
time Long Yes Data time range, determines the time dimension for the query. Values: 3-All data (no time limit), 4-Yesterday data, 0-Last 7 days data, 1-Last 1 month (30 days) data, 2-Last 3 months (90 days) data. Note: When time != 0, related data fields will return change/increment data within that time range
sort Integer Yes Sort field. Values: 0-Sort by ad count, 1-Sort by ad play count (when data_type=3, means sort by reach/ad plays), 2-Sort by like count, 4-Sort by placement days, 6-Sort by ad spend (USD), 7-Sort by ad start date, 8-Sort by ad end date, 10-Sort by monthly visit traffic, 13-Sort by estimated order count, 14-Sort by advertiser count
sort_type String Yes Sort order, used with sort. Values: desc-Descending (large to small), asc-Ascending (small to large)
page_size Integer Yes Records per page, specifies the number of advertisers returned per page. Recommended to set between 20-200
current_page Integer Yes Current page number, page numbers start from 1
keyword String No Keyword search, used for fuzzy matching advertiser-related information. Supports searching advertiser names and advertiser URLs. System automatically removes https://, http://, www. and other prefixes. Recommended to use pure domain names for searching. Must be used with search_type parameter
search_type Integer No Keyword search type, specifies the search scope of the keyword parameter. Values: 1-Search by keyword (results can be advertiser name or advertiser URL), 5-Search by advertiser name, 4-Search by advertiser URL
start_time_start Long No Ad start date - start value, used for filtering advertisers with ad start dates within the specified range. Data type: timestamp (seconds). Queries the corresponding platform's ad start time based on data_type
start_time_end Long No Ad start date - end value, used with start_time_start to define the upper limit of the time range. Data type: timestamp (seconds)
end_time_start Long No Ad end date - start value, used for filtering advertisers with ad end dates within the specified range. Data type: timestamp (seconds). Queries the corresponding platform's ad end time based on data_type
end_time_end Long No Ad end date - end value, used with end_time_start to define the upper limit of the time range. Data type: timestamp (seconds)
goods_source_min Long No Ad count - minimum value, used for filtering advertisers with ad counts within the specified range. Counts the corresponding platform's ad count based on data_type
goods_source_max Long No Ad count - maximum value, used with goods_source_min to define the upper limit of the ad count range
play_count_min Long No Ad play count - minimum value, used for filtering advertisers with ad play counts within the specified range. Play count refers to the total number of video ad plays. Counts the corresponding platform's play count based on data_type
play_count_max Long No Ad play count - maximum value, used with play_count_min to define the upper limit of the play count range
put_day_min Long No Placement days - minimum value, used for filtering advertisers with placement days within the specified range
put_day_max Long No Placement days - maximum value, used with put_day_min to define the upper limit of the placement days range
cpm_min Double No CPM (cost per thousand impressions) - minimum value, used for filtering advertisers with CPM within the specified range, unit: USD. This is an estimated value, for reference only
cpm_max Double No CPM (cost per thousand impressions) - maximum value, used with cpm_min to define the upper limit of the CPM range, unit: USD
cpa_min Long No Estimated order conversion count - minimum value, used for filtering advertisers with estimated order conversion counts within the specified range. This is the estimated number of orders based on ad data and industry standards, for reference only
cpa_max Long No Estimated order conversion count - maximum value, used with cpa_min to define the upper limit of the estimated order count range
ad_state Integer No Ad status, used for filtering advertisers with specified ad statuses. Values: -1-Stopped placement (ads stopped), 1-Active (recent ad placement records, usually within the last 3 days)
shop_type String Array No E-commerce system type list, used for filtering advertisers using specified website building systems. Supported: shopify, woocommerce, magento, shoplazza, shopline, shopyy, squarespace, wix, prestashop, bigcommerce, ecwid, cafe24, wordpress, etc. Example: ["shopify", "woocommerce"]
region String Array No List of countries where the advertiser's ads are located, see Regions, used for filtering advertisers with ad registration/location countries within the specified range. Uses ISO 3166-1 alpha-2 standard country codes (2 uppercase letters). Example: ["US", "CA", "GB"]
ad_language String Array No List of languages used in advertiser ads, used for filtering advertisers with ads using specified languages. Uses ISO 639-1 standard language codes (2 lowercase letters). Example: ["en", "de"]
product_category_id String Array No Product category ID list, see E-commerce Categories, used for filtering advertisers in specified product categories (Niches). Need to pass the unique identifier ID of the product category (MongoDB ObjectId format). Example: ["62739afc38365b2f72048ebe", "62739b0438365b2f72048ebf"]
product_count_min Long No Product count - minimum value, used for filtering advertisers with product counts within the specified range. Product count refers to the number of different products promoted by the advertiser through ads
product_count_max Long No Product count - maximum value, used with product_count_min to define the upper limit of the product count range
page_count_min Long No Associated advertiser count - minimum value, used for filtering advertisers with associated advertiser (Page/Account) counts within the specified range. Advertiser count refers to the number of different advertiser accounts placing ads for this advertiser. Counts the corresponding platform's advertiser count based on data_type
page_count_max Long No Associated advertiser count - maximum value, used with page_count_min to define the upper limit of the advertiser count range
website_monthly_visits_min Long No Website monthly visits - minimum value, used for filtering advertisers with website monthly visits within the specified range. Data sourced from third-party traffic statistics tools. This parameter is not affected by time and data_type
website_monthly_visits_max Long No Website monthly visits - maximum value, used with website_monthly_visits_min to define the upper limit of the monthly visits range
reach_min Long No Meta Ad Library reach - minimum value, only effective when data_type=3. Reach refers to the number of unique users who saw the ad at least once, data sourced from Meta Ad Library public data
reach_max Long No Meta Ad Library reach - maximum value, only effective when data_type=3. Used with reach_min to define the upper limit of the reach range
facebook_library_ad_platform String Array No Meta Ad Library placement platform list, only effective when data_type=3. Supported: FACEBOOK, INSTAGRAM, AUDIENCE_NETWORK, MESSENGER, THREADS. Example: ["FACEBOOK", "INSTAGRAM"]

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/top-advertiser/list",
    "params": {
      "time": 0,
      "sort": 0,
      "sort_type": "desc",
      "current_page": 1,
      "data_type": 0,
      "page_size": 20
    }
  }'

Response Parameters

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

Field Type Description
code Integer Response status code, 200 indicates success
message String Response message
data Object Response data
data.data Array Advertiser leaderboard list
data.page Object Pagination information
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

Advertiser Leaderboard Information Fields

Field Type Description
id String Data record ID
root_path String Advertiser path identifier (for tracking ad source)
shop_type String Primary type (shopify, woocommerce, etc.)
plat_type Array List of platforms placing ads (tiktok, facebook, facebook-library)
icon String Primary avatar image URL
is_collection Boolean Whether the current user has collected this primary
popular_person_count Long Number of users following this primary
all_data_count Long Total ad count across all platforms
all_play_count Long Total ad impression count across all platforms
all_digg_count Long Total ad like count across all platforms
all_put_days Long Ad placement days across all platforms
all_found_time Long Earliest ad start time across all platforms (timestamp, seconds)
all_latest_found_time Long Latest ad time across all platforms (timestamp, seconds)
all_min_cpm Double Minimum CPM across all platforms (USD)
all_max_cpm Double Maximum CPM across all platforms (USD)
all_min_cpa Long Minimum estimated order count across all platforms
all_max_cpa Long Maximum estimated order count across all platforms
all_page_count Long Total advertiser account count across all platforms
all_store_ad_state Integer Overall ad status (-1=stopped, 1=active)
tiktok_data_count Long Total ad count on TikTok platform
tiktok_play_count Long Total ad impression count on TikTok platform
tiktok_page_count Long Total advertiser account count on TikTok platform
facebook_data_count Long Total ad count on Facebook platform
facebook_play_count Long Total ad impression count on Facebook platform
facebook_page_count Long Total advertiser account count on Facebook platform
facebook_library_data_count Long Total ad count in Facebook Ad Library
facebook_library_play_count Long Total ad impression count in Facebook Ad Library
facebook_library_reach Long Facebook Ad Library reach
facebook_library_adset_count Long Total ad set count in Facebook Ad Library
facebook_library_adset_active_count Long Active ad set count currently being placed in Facebook Ad Library
facebook_library_ad_active_count Long Active ad count currently being placed in Facebook Ad Library
facebook_library_ad_inactive_count Long Paused ad count in Facebook Ad Library
facebook_library_ad_offline_count Long Offline ad count in Facebook Ad Library
facebook_library_page_count Long Total advertiser account count in Facebook Ad Library
facebook_library_ad_platform Array Ad library ad platforms (FACEBOOK, INSTAGRAM, MESSENGER, etc.)
good_source Array Latest 3 ads published by the advertiser
website_info Object Advertiser website information

Product Source Information Fields (good_source)

Field Type Description
cover String Ad cover image URL
app_image String App icon image URL
count Long Video play count
video_id String Associated video ID

Website Information Fields (website_info)

Field Type Description
website_id String Website unique identifier
website_url String Website link
website_title String Website title
website_monthly_visits Long Website monthly visits
website_bounce_rate Double Website bounce rate (0.0-1.0)
website_visit_seconds Long Website average visit duration (seconds)

Pagination Information Fields

Field Type Description
total_count Long Total record count
page_count Long Total page count
current_page Long Current page number
page_size Long Records per page
is_next Boolean Whether there is a next page

Response Example

{
  "code": 200,
  "message": "success",
  "data": {
    "data": [
      {
        "id": "61f57e4d9a301ef93d53b88a",
        "root_path": "shop.tiktok.com",
        "shop_type": "shopify",
        "plat_type": ["tiktok", "facebook"],
        "icon": "https://fb-cdn.pipispy.com/images/8caaedcdf7b129675d8eb51c552c7eac.png",
        "all_data_count": 2285852,
        "all_play_count": 76792774635,
        "all_digg_count": 661586882,
        "all_put_days": 59,
        "all_found_time": 1700000000,
        "all_latest_found_time": 1700086400,
        "all_page_count": 3256,
        "all_min_cpm": 15.5,
        "all_max_cpm": 45.8,
        "popular_person_count": 1157348,
        "is_collection": false,
        "good_source": [
          {
            "cover": "https://fb-cdn.pipispy.com/images/cover1.png",
            "app_image": "https://fb-cdn.pipispy.com/images/app1.png",
            "count": 1088,
            "video_id": "video_001"
          },
          {
            "cover": "https://fb-cdn.pipispy.com/images/cover2.png",
            "app_image": "https://fb-cdn.pipispy.com/images/app2.png",
            "count": 5715,
            "video_id": "video_002"
          },
          {
            "cover": "https://fb-cdn.pipispy.com/images/cover3.png",
            "app_image": "https://fb-cdn.pipispy.com/images/app3.png",
            "count": 172,
            "video_id": "video_003"
          }
        ],
        "website_info": {
          "website_id": "web_001",
          "website_url": "https://shop.tiktok.com",
          "website_title": "TikTok Shop",
          "website_monthly_visits": 5000000,
          "website_bounce_rate": 0.45,
          "website_visit_seconds": 180
        }
      }
    ],
    "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 Descriptions

Error Code Description
200 Success
400 Request parameter error
401 Unauthorized
403 Insufficient permissions
444 Too many requests, rate limit triggered
500 Internal server error