Pipispy APIEnglish

广告主榜单列表接口

接口信息

  • 接口名称: 获取广告主榜单列表
  • 请求方法: POST
  • 接口地址: /open-api/v1/data
  • 接口路径: /v3/api/open/rank/top-advertiser/list
  • 接口描述: 根据过滤条件获取广告主榜单列表信息，支持分页
  • 价格说明: 获取一条数据结果消耗1 credit

请求头:

  • Content-Type: application/json
  • Accept: application/json

请求参数

请求结构

参数名 类型 描述 示例 必填 默认值
key
string
用户申请的外部 api 请求 key
"your_api_key_here"
是
uri
string
接口路径
"/v3/api/open/rank/top-advertiser/list"
是
params
object
接口入参对象
见参数列表
是

请求体参数 (params 对象)

参数名 类型 必填 描述
data_type
Integer
是
数据平台类型，决定查询哪个平台的广告主数据。取值：0-全平台数据（TikTok + Facebook + Meta广告资料库三个平台的汇总数据），1-TikTok平台数据，2-Facebook平台数据，3-Meta广告资料库数据。此参数会影响其他筛选字段的数据来源和统计口径
ad_type
Integer
否
广告主类型，取值：0-网站，3-电商，4-AI，5-短剧
time
Long
是
数据时间范围，决定查询的时间维度。取值：3-全部数据（不限时间），4-昨天数据，0-近7天数据，1-近1个月（30天）数据，2-近3个月（90天）数据。注意：当time != 0时，相关数据字段将返回该时间范围内的变化/增量数据
sort
Integer
是
排序字段。取值：0-按广告数排序，1-按广告播放数排序（当data_type=3时表示按覆盖人数/广告播放排序），2-按点赞数排序，4-按投放天数排序，6-按广告花费（USD）排序，7-按广告开始日期排序，8-按广告结束日期排序，10-按月访问流量排序，13-按预估订单数排序，14-按广告主数排序
sort_type
String
是
排序方式，与sort配合使用。取值：desc-降序（从大到小），asc-升序（从小到大）
page_size
Integer
是
每页记录数，指定单页返回的广告主数量。建议设置在20-200之间
current_page
Integer
是
当前页码，页码从1开始
keyword
String
否
关键词搜索，用于模糊匹配广告主相关信息。支持搜索广告主名字和广告主URL，系统会自动去除https://、http://、www.等前缀，建议使用纯域名进行搜索，需配合search_type参数使用
search_type
Integer
否
关键词搜索类型，指定keyword参数的搜索范围。取值：1-按关键词搜索（结果可以是广告主名字或广告主URL），5-按广告主名字搜索，4-按广告主URL搜索
start_time_start
Long
否
广告开始日期-起始值，用于筛选广告开始日期在指定范围内的广告主。数据类型：时间戳（秒）。根据data_type查询对应平台的广告开始时间
start_time_end
Long
否
广告开始日期-结束值，与start_time_start配合使用，定义时间范围的上限。数据类型：时间戳（秒）
end_time_start
Long
否
广告结束日期-起始值，用于筛选广告结束日期在指定范围内的广告主。数据类型：时间戳（秒）。根据data_type查询对应平台的广告结束时间
end_time_end
Long
否
广告结束日期-结束值，与end_time_start配合使用，定义时间范围的上限。数据类型：时间戳（秒）
goods_source_min
Long
否
广告数量-最小值，用于筛选广告主广告数量在指定范围内的广告主。根据data_type统计对应平台的广告数
goods_source_max
Long
否
广告数量-最大值，与goods_source_min配合使用，定义广告数量范围的上限
play_count_min
Long
否
广告播放数-最小值，用于筛选广告播放数在指定范围内的广告主。播放数是指视频广告的播放次数总和。根据data_type统计对应平台的播放数
play_count_max
Long
否
广告播放数-最大值，与play_count_min配合使用，定义播放数范围的上限
put_day_min
Long
否
投放天数-最小值，用于筛选广告投放天数在指定范围内的广告主
put_day_max
Long
否
投放天数-最大值，与put_day_min配合使用，定义投放天数范围的上限
cpm_min
Double
否
CPM（千次展示成本）-最小值，用于筛选广告CPM在指定范围内的广告主，单位：美元（USD）。这是预估值，仅供参考
cpm_max
Double
否
CPM（千次展示成本）-最大值，与cpm_min配合使用，定义CPM范围的上限，单位：美元（USD）
cpa_min
Long
否
预估订单转化数-最小值，用于筛选预估订单转化数在指定范围内的广告主。这是根据广告数据和行业标准预估的订单数量，仅供参考
cpa_max
Long
否
预估订单转化数-最大值，与cpa_min配合使用，定义预估订单数范围的上限
ad_state
Integer
否
广告状态，用于筛选指定广告状态的广告主。取值：-1-停止投放（广告已停止），1-活跃（近期有广告投放记录，通常指最近3天内）
shop_type
String Array
否
电商系统类型列表，用于筛选使用指定建站系统的广告主。支持：shopify、woocommerce、magento、shoplazza、shopline、shopyy、squarespace、wix、prestashop、bigcommerce、ecwid、cafe24、wordpress等。示例：["shopify", "woocommerce"]
region
String Array
否
广告主包含的广告所在国家列表，见 国家地区 ，用于筛选广告注册地/所在国家在指定范围内的广告主。使用ISO 3166-1 alpha-2标准的国家代码（2位大写字母）。示例：["US", "CA", "GB"]
ad_language
String Array
否
广告主广告使用语言列表，用于筛选广告使用指定语言的广告主。使用ISO 639-1标准的语言代码（2位小写字母）。示例：["en", "de"]
product_category_id
String Array
否
产品分类ID列表，见 电商分类 ，用于筛选指定产品分类（Niche）的广告主。需要传递产品分类的唯一标识ID（MongoDB ObjectId格式）。示例：["62739afc38365b2f72048ebe", "62739b0438365b2f72048ebf"]
product_count_min
Long
否
产品数量-最小值，用于筛选广告主产品数量在指定范围内的广告主。产品数量是指广告主通过广告推广的不同产品数量
product_count_max
Long
否
产品数量-最大值，与product_count_min配合使用，定义产品数量范围的上限
page_count_min
Long
否
关联广告主数量-最小值，用于筛选关联广告主（Page/Account）数量在指定范围内的广告主。广告主数量是指为该广告主投放广告的不同广告主账号数量。根据data_type统计对应平台的广告主数
page_count_max
Long
否
关联广告主数量-最大值，与page_count_min配合使用，定义广告主数量范围的上限
website_monthly_visits_min
Long
否
网站月访问量-最小值，用于筛选网站月访问量在指定范围内的广告主。数据来源于第三方流量统计工具，此参数不受time和data_type影响
website_monthly_visits_max
Long
否
网站月访问量-最大值，与website_monthly_visits_min配合使用，定义月访问量范围的上限
reach_min
Long
否
Meta广告资料库覆盖人数-最小值，仅当data_type=3时生效。覆盖人数（Reach）是指广告至少展示一次的独立用户数量，数据来源于Meta广告资料库公开数据
reach_max
Long
否
Meta广告资料库覆盖人数-最大值，仅当data_type=3时生效。与reach_min配合使用，定义覆盖人数范围的上限
facebook_library_ad_platform
String Array
否
Meta广告资料库投放平台列表，仅当data_type=3时生效。支持：FACEBOOK、INSTAGRAM、AUDIENCE_NETWORK、MESSENGER、THREADS。示例：["FACEBOOK", "INSTAGRAM"]

请求示例

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

响应参数

响应体结构

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

响应字段说明

字段名 类型 描述
code
Integer
响应状态码，200 表示成功
message
String
响应消息
data
Object
响应数据
data.data
Array
广告主榜单列表
data.page
Object
分页信息
version
String
API 版本
timestamp
String
响应时间戳
sign
String
响应签名
remaining_credits
Long
当前请求后的剩余可用积分
consumed_credits
Long
本次请求消耗的积分
success
Boolean
请求是否成功
fail
Boolean
请求是否失败

广告主榜单信息字段

字段名 类型 描述
id
String
数据记录ID
root_path
String
广告主路径标识（用于追踪广告来源）
shop_type
String
主类型（shopify、woocommerce等）
plat_type
Array
投放广告的平台列表（tiktok、facebook、facebook-library）
icon
String
主头像图片地址
is_collection
Boolean
当前用户是否已收藏该主
popular_person_count
Long
关注该主的用户数量
all_data_count
Long
所有平台的广告总数
all_play_count
Long
所有平台的广告曝光总次数
all_digg_count
Long
所有平台的广告点赞总数
all_put_days
Long
所有平台的广告投放天数
all_found_time
Long
所有平台中最早的广告开始时间（时间戳，秒）
all_latest_found_time
Long
所有平台中最近的广告时间（时间戳，秒）
all_min_cpm
Double
所有平台的最小CPM（美元）
all_max_cpm
Double
所有平台的最大CPM（美元）
all_min_cpa
Long
所有平台的最小预估订单数
all_max_cpa
Long
所有平台的最大预估订单数
all_page_count
Long
所有平台的广告主账号总数
all_store_ad_state
Integer
总广告状态（-1=停止，1=活跃）
tiktok_data_count
Long
TikTok平台的广告总数
tiktok_play_count
Long
TikTok平台的广告曝光总次数
tiktok_page_count
Long
TikTok平台的广告主账号总数
facebook_data_count
Long
Facebook平台的广告总数
facebook_play_count
Long
Facebook平台的广告曝光总次数
facebook_page_count
Long
Facebook平台的广告主账号总数
facebook_library_data_count
Long
Facebook广告库中的广告总数
facebook_library_play_count
Long
Facebook广告库的广告曝光总次数
facebook_library_reach
Long
Facebook广告库覆盖人数
facebook_library_adset_count
Long
Facebook广告库中的广告组总数
facebook_library_adset_active_count
Long
Facebook广告库中正在投放的活跃广告组数量
facebook_library_ad_active_count
Long
Facebook广告库中正在投放的活跃广告数量
facebook_library_ad_inactive_count
Long
Facebook广告库中已暂停投放的广告数量
facebook_library_ad_offline_count
Long
Facebook广告库中已下线的广告数量
facebook_library_page_count
Long
Facebook广告库中的广告主账号总数
facebook_library_ad_platform
Array
广告库广告平台（FACEBOOK、INSTAGRAM、MESSENGER等）
good_source
Array
广告主最新发布的3条广告信息
website_info
Object
广告主网站信息

商品源信息字段（good_source）

字段名 类型 描述
cover
String
广告封面图片URL
app_image
String
应用图标图片URL
count
Long
视频播放量
video_id
String
关联视频ID

网站信息字段（website_info）

字段名 类型 描述
website_id
String
网站唯一标识
website_url
String
网站链接
website_title
String
网站标题
website_monthly_visits
Long
网站月访问量
website_bounce_rate
Double
网站跳出率（0.0-1.0）
website_visit_seconds
Long
网站平均访问时长（秒）

分页信息字段

字段名 类型 描述
total_count
Long
总记录数
page_count
Long
总页数
current_page
Long
当前页码
page_size
Long
每页记录数
is_next
Boolean
是否有下一页

响应示例

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

错误码说明

错误码 描述
200
成功
400
请求参数错误
401
未授权
403
权限不足
444
请求过于频繁，已触发限流
500
服务器内部错误