# 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](https://www.pipispy.com/zh/doc/others-region), 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](https://www.pipispy.com/zh/doc/others-product-category), 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 ```bash 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 ```json { "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 ```json { "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 |