# 广告主榜单列表接口 ## 接口信息 - **接口名称**: 获取广告主榜单列表 - **请求方法**: POST - **接口地址**: `/open-api/v1/data` - **接口路径**: `/v3/api/open/rank/advertiser/list` - **接口描述**: 根据过滤条件获取广告主榜单列表信息，支持分页 **请求头:** - Content-Type: application/json - Accept: application/json ## 请求参数 ### 请求结构 | 参数名 | 类型 | 描述 | 示例 | 必填 | 默认值 | | ------ | ------ | --------------------------- | ----------------------------------- | ---- | ------ | | key | string | 用户申请的外部 api 请求 key | "your_api_key_here" | 是 | | | uri | string | 接口路径 | "/v3/api/open/rank/advertiser/list" | 是 | | | params | object | 接口入参对象 | 见参数列表 | 是 | | ### 请求体参数 (params 对象) | 参数名 | 类型 | 必填 | 描述 | | ---------------- |---------| ---- |--------------------------------------------------------------------------------------------------------| | current_page | Integer | 是 | 当前页码，分页查询的当前页数，从 1 开始 | | page_size | Integer | 是 | 每页大小，分页查询的每页记录数 | | sort | String | 是 | 排序字段：0-总广告数，1-广告播放数，2-总点赞数，4-总投放天数，7-总开始时间，8-总结束时间 | | sort_type | String | 是 | 排序类型：desc-降序，asc-升序 | | time | Integer | 是 | 时间范围：0-默认，1-昨天，2-近3天，3-近7天，4-近1个月，5-近3个月，6-近6个月 | | count_growth_max | Double | 否 | 广告播放，数据增长最大值（播放量增长），用于筛选增长量不超过指定值的广告主 | | count_growth_min | Double | 否 | 广告播放，数据增长最小值（播放量增长），用于筛选增长量不低于指定值的广告主 | | put_day_max | Long | No | 投放天数 | | put_day_min | Long | No | 投放天数 | | growth_rate_max | Double | 否 | 点赞数，数据增长比例最大值，用于筛选增长率不超过指定值的广告主 | | growth_rate_min | Double | 否 | 点赞数，数据增长比例最小值，用于筛选增长率不低于指定值的广告主 | | play_count_max | Long | 否 | 广告播放 | | play_count_min | Long | 否 | 广告播放 | | plat_type | Integer | 否 | 平台类型：0-全平台，1-TikTok，2-Facebook | | region | String | 否 | 国家/地区，多个用逗号分隔 | | goods_source_max | long | No | 广告数 | | goods_source_min | long | No | 广告数 | | shop_type | String Array | No | 电商系统, e.g "magento", "shopify", "shoplazza", "shopline", "shopyy", "squarespace", "wix", "woocommerce" | | start_time_start | long | No | 广告开始时间 | | start_time_end | long | No | 广告开始时间 | | end_time_start | long | No | 广告结束时间 | | end_time_end | long | No | 广告结束时间 | ### 请求示例 ```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 } }' ``` ## 响应参数 ### 响应体结构 ```json { "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 | | icon | String | 广告主图标/logo URL | | region | Array | 目标地区数组（国家代码） | | root_path | String | 广告主名 | | plat_type | Array | 平台类型数组（如：["tiktok", "facebook"]） | | goods_source_count | Long | 商品源总数 | | play_change | Long | 播放量变化/增长 | | put_day_change | Integer | 距离上次更新的天数 | | digg_change | Long | 点赞量变化/增长 | | found_time | Long | 首次发现时间戳 | | last_found_time | Long | 最后发现时间戳 | | good_source | Array | 热门商品源信息 | | is_collection | Boolean | 是否已收藏 | | popular_person_count | Long | 热门人物/创作者数量 | ### 商品源信息字段 | 字段名 | 类型 | 描述 | | --------- | ------- | ---------------- | | cover | String | 商品封面图片 URL | | app_image | String | 应用图标图片 URL | | count | Integer | 商品数量 | | video_id | String | 关联视频 ID | ### 分页信息字段 | 字段名 | 类型 | 描述 | | ------------ | ------- | ------------ | | total_count | Long | 总记录数 | | page_count | Long | 总页数 | | current_page | Long | 当前页码 | | page_size | Long | 每页记录数 | | is_next | Boolean | 是否有下一页 | ## 响应示例 ```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 } ``` ## 错误码说明 | 错误码 | 描述 | | ------ | -------------- | | 200 | 成功 | | 400 | 请求参数错误 | | 500 | 服务器内部错误 |