# 广告店铺榜单列表接口 ## 接口信息 - **接口名称**: 获取广告店铺榜单列表 - **请求方法**: POST - **接口地址**: `/open-api/v1/data` - **接口路径**: `/v3/api/open/rank/store/list` - **接口描述**: 根据过滤条件获取广告店铺榜单列表信息，支持分页 - **价格说明**: 获取一条数据结果消耗1 credit **请求头:** - Content-Type: application/json - Accept: application/json ## 请求参数 ### 请求结构 | 参数名 | 类型 | 描述 | 示例 | 必填 | 默认值 | | ------ | ------ | --------------------------- | ------------------------------ | ---- | ------ | | key | string | 用户申请的外部 api 请求 key | "your_api_key_here" | 是 | | | uri | string | 接口路径 | "/v3/api/open/rank/store/list" | 是 | | | params | object | 接口入参对象 | 见参数列表 | 是 | | ### 请求体参数 (params 对象) | 参数名 | 类型 | 必填 | 描述 | | ------ | ---- | ---- |-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | data_type | Integer | 是 | 数据平台类型，决定查询哪个平台的广告店铺数据。取值：0-全平台数据（TikTok + Facebook + Meta广告资料库三个平台的汇总数据），1-TikTok平台数据，2-Facebook平台数据，3-Meta广告资料库数据。此参数会影响其他筛选字段的数据来源和统计口径 | | 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"] | | store_countries | String Array | 否 | 店铺所在国家列表，见 [国家地区](https://www.pipispy.com/zh/doc/others-region) ，用于筛选店铺注册地/所在国家在指定范围内的店铺。使用ISO 3166-1 alpha-2标准的国家代码（2位大写字母）。示例：["US", "CA", "GB"] | | store_languages | String Array | 否 | 店铺使用语言列表，用于筛选店铺使用指定语言的店铺。使用ISO 639-1标准的语言代码（2位小写字母）。示例：["en", "de"] | | product_category_id | String Array | 否 | 产品分类ID列表，见 [电商分类](https://www.pipispy.com/zh/doc/others-product-category) ，用于筛选指定产品分类（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"] | ### 请求示例 ```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/store/list", "params": { "time": 0, "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 | | store_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 | 是否有下一页 | ## 响应示例 ```json { "code": 200, "message": "success", "data": { "data": [ { "id": "61f57e4d9a301ef93d53b88a", "store_id": "store_123456", "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 | 权限不足 | | 500 | 服务器内部错误 |