# Advertiser Rank List API ## API Information - **API Name**: Get Advertiser Rank List - **Request Method**: POST - **API URL**: `/open-api/v1/data` - **Interface URI path**: `/v3/api/open/rank/advertiser/list` - **Description**: Get advertiser rank list information based on filter conditions with pagination support **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/advertiser/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 | String | Yes | Sort field: 0-Number of ads，1-Impressions，2-Likes，4-Durations，7-Start Date，8-End Date | | sort_type | String | Yes | Sort type: desc-descending, asc-ascending | | time | Integer | Yes | Time range: 0-default, 1-yesterday, 2-last 3 days, 3-last 7 days, 4-last 1 month, 5-last 3 months, 6-last 6 months | | count_growth_max | Double | No | Data growth maximum value (play count growth), used to filter advertisers with growth not exceeding specified value | | count_growth_min | Double | No | Data growth minimum value (play count growth), used to filter advertisers with growth not below specified value | | put_day_max | Long | No | Ad Run Time | | put_day_min | Long | No | Ad Run Time | | growth_rate_max | Double | No | Data growth rate maximum value, used to filter advertisers with growth rate not exceeding specified value | | growth_rate_min | Double | No | Data growth rate minimum value, used to filter advertisers with growth rate not below specified value | | play_count_max | Long | 否 | Impressions | | play_count_min | Long | 否 | Impressions | | plat_type | Integer | No | Platform type: 0-all platforms, 1-TikTok, 2-Facebook | | region | String | No | Target regions, multiple separated by commas | | goods_source_max | long | No | Number of ads | | goods_source_min | long | No | Number of ads | | shop_type | String Array | No | Ecom Platform, e.g "magento", "shopify", "shoplazza", "shopline", "shopyy", "squarespace", "wix", "woocommerce" | | start_time_start | long | No | Start Date | | start_time_end | long | No | Start Date | | end_time_start | long | No | End Date | | end_time_end | long | No | End Date | ### 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/advertiser/list", "params": { "time": 1, "search_type": 1, "sort": 0, "sort_type": "desc", "current_page": 1, "data_type": 0, "page_size": 20 } }' ``` ## Response Parameters ### Response Body 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 Description | Field Name | Type | Description | | ---------- | ------- | ------------------------------------------- | | code | Integer | Response status code, 200 indicates success | | message | String | Response message | | data | Object | Response data | | data.data | Array | Advertiser rank 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 Rank Information Fields | Field Name | Type | Description | | -------------------- | ------- | --------------------------------------------------- | | id | String | Advertiser unique identifier ID | | icon | String | Advertiser icon/logo URL | | region | Array | Target regions array (country codes) | | root_path | String | Advertiser's root domain path | | plat_type | Array | Platform types array (e.g., ["tiktok", "facebook"]) | | goods_source_count | Long | Total number of goods sources | | play_change | Long | Play count change/growth | | put_day_change | Integer | Number of days since last update | | digg_change | Long | Like count change/growth | | found_time | Long | First discovery timestamp | | last_found_time | Long | Last discovery timestamp | | good_source | Array | Top goods sources information | | is_collection | Boolean | Whether already collected | | popular_person_count | Long | Number of popular persons/creators | ### Goods Source Information Fields | Field Name | Type | Description | | ---------- | ------- | --------------------- | | cover | String | Goods cover image URL | | app_image | String | App icon image URL | | count | Integer | Goods count | | video_id | String | Associated video ID | ### 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 ```json { "code": 200, "message": "success", "data": { "data": [ { "id": "61f57e4d9a301ef93d53b88a", "icon": "https://fb-cdn.pipispy.com/images/8caaedcdf7b129675d8eb51c552c7eac.png", "region": [ "DE", "TW", "JP", "FR", "SA", "BR", "SG", "ID", "GB", "IE", "US", "CA", "ST", "AE", "KR", "IT", "GR", "MY", "ES", "TH", "AU", "CZ", "PH", "VN", "PK", "TR", "NL", "PT", "LA", "DK", "NO", "CH", "RU", "RO", "BD", "SE", "BE", "FI", "AT", "EG", "PL", "HU", "IN", "MX", "UA", "HK", "SC", "KH" ], "root_path": "shop.tiktok.com", "plat_type": ["tiktok", "facebook"], "goods_source_count": 2285852, "play_change": 76792774635, "put_day_change": 59, "digg_change": 661586882, "found_time": 1749571200, "last_found_time": 1752076800, "good_source": [ { "cover": "https://fb-cdn.pipispy.com/images/45934281c9a2b9d624345deb27896607.png", "app_image": "https://fb-cdn.pipispy.com/images/8caaedcdf7b129675d8eb51c552c7eac.png", "count": 1088, "video_id": "f09e695769a92b9e5ceba" }, { "cover": "https://fb-cdn.pipispy.com/images/04f94a47ec9f1472c0461932b60a70d6.png", "app_image": "https://fb-cdn.pipispy.com/images/fca54fbd0c19f7fb306b12fed3417533.png", "count": 5715, "video_id": "f20bdd186b27bcc10393c" }, { "cover": "https://fb-cdn.pipispy.com/images/3d70d471ffd36f542a4b3b05d16084e3.png", "app_image": "https://fb-cdn.pipispy.com/images/fca54fbd0c19f7fb306b12fed3417533.png", "count": 172, "video_id": "f583b75099f6bdc020a70" } ], "is_collection": false, "popular_person_count": 1157348 } ], "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 | | 500 | Server internal error |