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

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

{
  "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

{
  "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