# Adspy 列表接口 ## 接口信息 - **接口名称**: 获取 Adspy 列表 - **请求方法**: POST - **接口地址**: `/open-api/v1/data` - **接口路径**: `/v3/api/open/adspy/list` - **接口描述**: 根据过滤条件获取 Adspy 列表信息，支持分页 - **价格说明**: 获取一条数据结果消耗1 credit **请求头:** - Content-Type: application/json - Accept: application/json ## 请求参数 ### 请求结构 | 参数名 | 类型 | 描述 | 示例 | 必填 | 默认值 | | ------ | ------ | --------------------------- | ----------------------------------- | ---- | ------ | | key | string | 用户申请的外部 api 请求 key | "your_api_key_here" | 是 | | | uri | string | 接口路径 | "/v3/api/open/adspy/list" | 是 | | | params | object | 接口入参对象 | 见参数列表 | 是 | | ### 参数列表 (params 对象) #### 必填参数 | 参数名 | 类型 | 描述 | 示例 | 必填 | 默认值 | | ------------ | ------ | ---------------- | ---- | ---- | ------ | | current_page | number | 当前页码（必填） | 1 | 是 | | | page_size | number | 每页数量（必填） | 10 | 是 | | #### 可选参数（按字母顺序） | 参数名 | 类型 | 描述 | 示例 | 必填 | 默认值 | |--------------------------| ------------ |-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------| ---- | ------ | | ad_cost_max | number | 广告花费最大值 | 1000.0 | 否 | | | ad_cost_min | number | 广告花费最小值 | 10.0 | 否 | | | ad_duration_max | number | 广告时长最大值（秒） | 60 | 否 | | | ad_duration_min | number | 广告时长最小值（秒） | 10 | 否 | | | ad_language | string array | 广告语言列表，支持"other"表示其他语言 | ["en"] | 否 | | | ad_state | number | 广告投放状态筛选。`TimeStampUtils.getToday()` 为 Asia/Shanghai 时区当前日期 00:00:00 的 Unix 秒级时间戳；`1` 表示投放中，筛选条件为 `modify_time >= TimeStampUtils.getToday()`，即广告在 Asia/Shanghai 当天凌晨后仍有投放相关更新或活跃记录；`0` 表示停止投放，筛选条件为 `modify_time <= TimeStampUtils.getToday()`，即最近一次投放相关更新时间不晚于 Asia/Shanghai 当天凌晨。当该参数不为空时，`last_time_start` 与 `last_time_end` 将被忽略，不再参与查询条件计算。 | 1=投放中，0=停止投放 | 否 | | | after | string array | 游标分页参数 | ["cursor1","cursor2"] | 否 | | | age | string array | 年龄范围列表，格式如"18-24" | ["25-35"] | 否 | | | ai_analysis_tags | string array | AI 分析标签列表，使用脚本分析标签查询 | ["tag1"] | 否 | | | ai_category | string array | AI 分类列表，使用 toolify 上的 AI 分类（暂未使用） | ["cat1"] | 否 | | | app_category | string array | App分类/游戏分类 | ["fashion","beauty"] | 否 | | | app_dev_id | string | APP开发者 ID | "dev123" | 否 | | | app_id | string | APP ID | "app123" | 否 | | | app_system | string | APP平台：ios/android，支持逗号分割的多平台 | "ios" | 否 | | | app_type | string | APP类型 | "ios" | 否 | | | aspect_ratio | string array | 分辨率列表：640×360、360×640、854×480、480×854、720×720、1080×1080、1280×720、720×1280、1920×1080、1080×1920、2560×1440、1440×2560 | ["720×1280"] | 否 | | | button | string array | CTA按钮，按钮类型列表 | ["Shop now"] | 否 | | | clarity | string array | 画质：SD、HD、Full HD、UHD/4K、8K | ["HD"] | 否 | | | comment_count_max | number | 互动量-评论次数最大值 | 500 | 否 | | | comment_count_min | number | 互动量-评论次数最小值 | 5 | 否 | | | create_time_end | number | 创建时间结束（时间戳） | 1709827199 | 否 | | | create_time_start | number | 创建时间开始（时间戳） | 1709654400 | 否 | | | data_type | number array | 数据类型列表：1-爆品跟卖，2-小店（TTS）广告，3-电商，4-Spark Ads，5-游戏，6-App，7-AI，8-短剧 | [1,2] | 否 | | | digg_count_max | number | 互动量-点赞次数最大值 | 1000 | 否 | | | digg_count_min | number | 互动量-点赞次数最小值 | 10 | 否 | | | digg_rate_max | number | 互动量-点赞率最大值 | 0.1 | 否 | | | digg_rate_min | number | 互动量-点赞率最小值 | 0.01 | 否 | | | download_count_max | number | APP下载次数最大值 | 1000 | 否 | | | download_count_min | number | APP下载次数最小值 | 10 | 否 | | | estimated_conversion_max | number | 预估转化最大值 | 0.1 | 否 | | | estimated_conversion_min | number | 预估转化最小值 | 0.01 | 否 | | | exclude_word | object array | 排除词汇列表,参考[关键词搜索格式说明](#关键词搜索格式说明) | [] | 否 | | | extend_keywords | object array | 扩展关键词列表,参考[关键词搜索格式说明](#关键词搜索格式说明) | [] | 否 | | | first_time_end | number | 首次发现时间结束（时间戳） | 1709827199 | 否 | | | first_time_start | number | 首次发现时间开始（时间戳） | 1709654400 | 否 | | | formate_type | number array | 广告格式 1-视频，2-图片，3-轮播图 | [1,2] | 否 | | | hot_value_max | number | 互动数最大值 | 1000 | 否 | | | hot_value_min | number | 互动数最小值 | 10 | 否 | | | interest | string | 兴趣特征 | "gaming" | 否 | | | is_and | boolean | 是否多词查询（AND/OR 逻辑），默认为 false（OR 逻辑） | false | 否 | false | | is_ad_fake | boolean | 非品牌广告（非Spark Ads） | false | 否 | | | is_app | boolean | 有APP产品 | true | 否 | | | is_participle | boolean | 是否分词，默认 true | true | 否 | true | | is_product | boolean | 有广告商品 | true | 否 | | | is_real | string | 是否真人广告：no-AI，yes-真人，为空默认查全部 | "yes" | 否 | | | is_recommend | number | 是否为推荐内容 | 0 | 否 | | | is_redirect | boolean | 有重定向连接 | false | 否 | | | is_tiktok_shop | boolean | 有小店产品 | false | 否 | | | is_url | number | URL 状态：0-无落地页链接，1-有落地页链接 | 1 | 否 | | | last_time_end | number | 最后发现时间结束（时间戳） | 1711036799 | 否 | | | last_time_start | number | 最后发现时间开始（时间戳） | 1710864000 | 否 | | | monthly_income_max | number | APP月收入(USD)最大值 | 100000.0 | 否 | | | monthly_income_min | number | APP月收入(USD)最小值 | 1000.0 | 否 | | | monthly_install_max | number | APP月安装量最大值 | 100000 | 否 | | | monthly_install_min | number | APP月安装量最小值 | 1000 | 否 | | | play_count_max | number | 播放次数最大值 | 10000 | 否 | | | play_count_min | number | 播放次数最小值 | 100 | 否 | | | plat_type | number | 平台类型：1-TikTok，2-Facebook | 1 | 否 | | | popular_person_id | string | 红人 ID | "person123" | 否 | | | product_category_id | string array | 分类，和广告产品页面分类相同 | ["cat1"] | 否 | | | product_id | string | 产品 ID | "prod123" | 否 | | | put_day_max | number | 投放天数最大值 | 30 | 否 | | | put_day_min | number | 投放天数最小值 | 1 | 否 | | | reaction_anger_max | number | Facebook 反应"Anger"最大值 | 1000 | 否 | | | reaction_anger_min | number | Facebook 反应"Anger"最小值 | 10 | 否 | | | reaction_care_max | number | Facebook 反应"Care"最大值 | 1000 | 否 | | | reaction_care_min | number | Facebook 反应"Care"最小值 | 10 | 否 | | | reaction_haha_max | number | Facebook 反应"Haha"最大值 | 1000 | 否 | | | reaction_haha_min | number | Facebook 反应"Haha"最小值 | 10 | 否 | | | reaction_love_max | number | Facebook 反应"Love"最大值 | 1000 | 否 | | | reaction_love_min | number | Facebook 反应"Love"最小值 | 10 | 否 | | | reaction_sad_max | number | Facebook 反应"Sad"最大值 | 1000 | 否 | | | reaction_sad_min | number | Facebook 反应"Sad"最小值 | 10 | 否 | | | reaction_wow_max | number | Facebook 反应"Wow"最大值 | 1000 | 否 | | | reaction_wow_min | number | Facebook 反应"Wow"最小值 | 10 | 否 | | | region | string array | 国家地区 | ["US","HK"] | 否 | | | release_time_end | number | APP 上架时间结束（时间戳） | 1709827199 | 否 | | | release_time_start | number | APP 上架时间开始（时间戳） | 1709654400 | 否 | | | root_path | string | 广告主 | "path1" | 否 | | | score_max | number | APP 评分最大值 | 5.0 | 否 | | | score_min | number | APP 评分最小值 | 3.0 | 否 | | | search_type | number | 搜索类型，1-广告关键词，2-广告文案，3-广告主，4-着陆页url，5-电商产品，6-TikTok Shop店铺，7-APP名称，8-APP开发者，9-社媒账号（主页名称），10-素材（脚本/钩子/标签），11-电商店铺/URL，12-TikTok Shop产品 | 1 | 否 | | | sex | number array | 受众-性别：1-男性，2-女性 | [1,2] | 否 | | | share_count_max | number | 互动量-分享次数最大值 | 500 | 否 | | | share_count_min | number | 互动量-分享次数最小值 | 5 | 否 | | | share_play_rate_max | number | 互动量-分享播放率最大值 | 0.01 | 否 | | | share_play_rate_min | number | 互动量-分享播放率最小值 | 0.001 | 否 | | | shop_type | string array | 电商系统，"magento", "shopify", "shoplazza", "shopline", "shopyy", "squarespace", "wix", "woocommerce" | ["ecommerce"] | 否 | | | size | string array | 画面比例列表：1:1、16:9、4:3、9:16、21:9、1:2、3:4、4:5、2:1、5:4 | ["9:16"] | 否 | | | skits_category | string array | 短剧分类列表（暂未使用） | ["cat1"] | 否 | | | sort | number | 排序方式：1:最后发现时间, 2:创建时间, 3:首次发现时间, 4:广告播放, 21:广告花费, 14:预估转换, 5:投放天数, 6:互动数, 7:点赞率, 8:转发比, 9:点赞数, 10:评论数, 11:分享数, 15:Wow, 16:Love, 17:Care, 18:Haha, 19:Sad, 20:Anger， 999：按搜索关键字分数排序，翻页时注意after参数要传入最后数据的_score及video_id，如：after:[921.20715, "2c219a83dc47a45a80ac"] | 1 | 否 | 2 | | sort_type | string | 排序类型 | "desc" | 否 | | | store_id | string | 店铺唯一标识ID，为13位字符串（例如：`c2d5b2547218a`），对应店铺榜单列表接口返回结果中的 `store_id` 字段 | "desc" | 否 | | | tk_shop_category_id | string array | TikTok Shop 分类 ID 列表 | ["cat1"] | 否 | | | aigc_type | string | AI创意: -1: AI生成，0: 非AI，1: 广告主标记，2: 官方AI | "-1" | 否 | | #### 关键词搜索格式说明 `extend_keywords` 和 `exclude_keywords` 参数使用 JSON 格式： ```json [ { "type": 1, "keyword": "搜索关键词" } ] ``` **搜索类型 (type) 说明**: - type:1 - 广告关键词搜索，用户输入的keyword 将会进行广告文案、广告主、落地页链接、产品、App、账号、素材匹配搜索 - type:2 - 广告文案，用户输入的keyword 只会进行广告文案匹配搜索 - type:3 - 广告主，用户输入的keyword将会对广告主进行搜索 - type:4 - 着陆页url，用户输入的keyword将会对落地页链接、重定向链接进行搜索 - type:5 - 电商产品，用户输入的keyword将会对电商产品名称进行搜索 - type:6 - TikTok Shop店铺，用户输入的keyword将会对TikTok Shop店铺名称进行搜索 - type:7 - APP名称，用户输入的keyword将会对App应用名称进行搜索 - type:8 - APP开发者，用户输入的keyword将会对APP开发者名称进行搜索 - type:9 - 社媒账号 (主页名称)，用户输入的keyword将会对社媒账号 (TT账号/Page ID)进行搜索 - type:10 - 素材 (脚本/钩子/标签)，用户输入的keyword素材信息 (脚本/钩子/标签)进行搜索 - type:11 - 电商店铺/URL，用户输入的keyword将会对电商店铺/URL进行搜索 - type:12 - TikTok Shop产品，用户输入的keyword将会对TikTok Shop产品进行搜索 ### 请求示例 ```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/adspy/list", "params": { "is_participle": false, "shop_type": [ "magento", "shopify" ], "extend_keywords": [ { "type": 1, "keyword": "shorts" }, { "type": 2, "keyword": "black" } ], "plat_type": 1, "search_type": 1, "sort": 2, "sort_type": "desc", "current_page": 1, "play_count_min": 1000, "play_count_max": 10000, "create_time_start": 1761580800, "create_time_end": 1764172799, "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** | number | 响应状态码，200 表示成功 | | **message** | string | 响应消息 | | **data** | object | 响应数据 | | **data.data** | array[object] | 广告数据列表 | | **data.page** | object | 分页信息 | | **version** | string | API 版本 | | **timestamp** | number | 响应时间戳 | | **sign** | string | 响应签名 | | **remaining_credits** | Long | 当前请求后的剩余可用积分 | | **consumed_credits** | Long | 本次请求消耗的积分 | | **success** | boolean | 请求是否成功 | | **fail** | boolean | 请求是否失败 | ##### 广告数据字段 (data) - 按字母顺序 | 字段名 | 类型 | 描述 | |-----------------------------| ------------- |-----------------------------------------------| | id | string | 视频 ID (访问广告详情用此字段作为id) | | video_id | string | 视频 ID (访问广告详情用此字段作为id) | | ad_create_time | number | 广告创建时间（时间戳） | | ai_analysis_human_presenter | string | AI 分析人类演示者 | | ai_analysis_language | string | AI 分析语言 | | ai_analysis_main_hook | string | AI 分析主要钩子 | | ai_analysis_script | string | AI 分析脚本 | | ai_analysis_tags | array[string] | AI 分析标签列表 | | app_dev_id | string | 应用开发者 ID | | app_image | string | 应用图片 URL | | app_name | string | 应用名称 | | app_title | string | 应用标题 | | button_text | string | 按钮文本 | | carousel | array[object] | 轮播图列表 | | comment_count | number | 评论数 | | cover | string | 封面图片 URL | | data_type | array[number] | 数据类型列表 | | desc | string | 广告描述 | | digg_count | number | 点赞数 | | digg_play_rate | number | 点赞播放率 | | duration | number | 时长（秒） | | facebook_link_angry | number | Facebook 愤怒反应数 | | facebook_link_care | number | Facebook 关心反应数 | | facebook_link_haha | number | Facebook 哈哈反应数 | | facebook_link_love | number | Facebook 喜欢反应数 | | facebook_link_sad | number | Facebook 悲伤反应数 | | facebook_link_wow | number | Facebook 惊讶反应数 | | fetch_region | array[string] | 抓取地区列表 | | found_time | number | 发现时间（时间戳） | | had_ai_analysis | boolean | 是否进行过 AI 分析 | | have_tiktok_shop | boolean | 是否有 TikTok 商店 | | hot_value | number | 热度值 | | image | string | 图片 URL | | is_collection | boolean | 是否收藏 | | is_download | boolean | 是否可下载 | | last_put_time | number | 最后投放时间（时间戳） | | min_cpa | number | 最小预估转换,由PIPIADS根据大数据和目标地区通用订单CPA指标自动计算而来（含误差） | | min_cpm | number | 最小广告花费,由PIPIADS根据大数据和目标地区通用CPM指标自动计算而来（含误差） | | modify_time | number | 修改时间（时间戳） | | pack_url | string | 包 URL | | platform | number | 平台类型（1:Facebook, 2:Instagram, 3:TikTok） | | play_count | number | 播放数 | | put_days | number | 投放天数 | | root_path_id | string | 广告主 ID | | search_by_image_tag | boolean | 是否通过图片标签搜索 | | share_count | number | 分享数 | | share_play_rate | number | 分享播放率 | | shop_type | string | 商店类型 | | type | number | 广告类型（1:视频, 2:图片） | | video_url | string | 视频 URL | | _score | Number | 搜索关键字分数 | | aigc_label_type | Number | AI创意: -1: AI生成，0: 非AI，1: 广告主标记，2: 官方AI | ##### 轮播图字段 (carousel) - 按字母顺序 | 字段名 | 类型 | 描述 | | ----------------------------------- | ------ | -------------------- | | aspect_ratio | string | 宽高比 | | body | string | 正文内容 | | button_text | string | 按钮文本 | | cta_text | string | CTA 文本 | | cover | string | 封面图片 URL | | cover_could_storage | string | 封面云存储 | | dimensions_type | number | 尺寸类型 | | duration | number | 时长（秒） | | height | number | 高度 | | image | string | 图片 URL | | image_could_storage | string | 图片云存储 | | link_description | string | 链接描述 | | link_url | string | 链接 URL | | play_count | number | 播放次数 | | quality | string | 质量 | | resolution | string | 分辨率 | | title | string | 标题 | | type | number | 类型 | | video_audio_user_preferred_language | string | 视频音频用户首选语言 | | video_url | string | 视频 URL | | video_url_could_storage | string | 视频 URL 云存储 | | width | number | 宽度 | ##### 分页信息字段 (page) | 字段名称 | 类型 | 描述 | | ------------ | ------- | ------------ | | total_count | number | 总记录数 | | page_count | number | 总页数 | | current_page | number | 当前页码 | | page_size | number | 每页大小 | | is_next | boolean | 是否有下一页 | ### 响应示例 ```json { "code": 200, "message": "success", "data": { "data": [ { "search_by_image_tag": true, "comment_count": 2, "app_dev_id": "", "digg_play_rate": 0.0067, "modify_time": 1752204344, "pack_url": "", "type": 1, "is_collection": false, "platform": 1, "duration": 59, "cover": "https://cdn-video.pipispy.com/cover_7f33700d982493b5a19b158a7068af93.jpg", "share_play_rate": 0.0007, "last_put_time": 1752204344, "root_path_id": "61f57e4d9a301ef93d53b88a", "put_days": 12, "app_title": "我不信！你的头发有比我油!! #amaxy #fyp", "fetch_region": ["MY"], "ad_create_time": 1745303145, "play_count": 47527, "share_count": 32, "app_name": "🇲🇾带货主播Regina & Fiona", "found_time": 1749614161, "ad_id": "1833892866239586", "hot_value": 352, "digg_count": 318, "is_download": false, "data_type": [3], "button_text": "Beli sekarang", "desc": "我不信！你的头发有比我油!! #amaxy #fyp", "video_id": "d9055376ae19819f4756", "app_image": "https://cdn-video.pipispy.com/avatar_0aa449789bac7929f216b33fde973196.jpg", "video_url": "https://cdn-video.pipispy.com/video_39551dc815f2501724d82a30c4a389c3.mp4", "ai_analysis_main_hook": "你们的头发有这么油吗？", "ai_analysis_script": "你们的头发有这么油吗？为了帮你们做测试啊，我牺牲几大，这个是油啊，哇啦喂，我又要做这个东西啊，啊，你们的头发有这么油吗？我跟你讲啊，我只会洗一次罢了，我看它的这个效果真的是可以帮我们去油没有？如果没有的话，不要买。OK，够了吗？你看它的泡沫还是蛮绵密，而且很香一下这种清香的味道啦，油头的话呢，你们就是买这个蓝色就可以了，它就帮你们去油了，再用一点它的这个conditioner，把它涂在发尾。有没有很顺滑？oh my god，我放了这么多油，我只洗一次罢了啊，你看它是干干净净，完全没有任何的油，也没有那种臭油味，而且是非常干爽，非常的蓬松，哇跟它讲的一样喔。所以如果你是油头的话，我非常建议你去买这个蓝色的amaxy，它是一个礼盒套装的，然后有两支shampoo，一支shampoo的话是400ml，然后这一个是conditioner，让你头发比较的顺滑，也是400ml。你买这个啊，百多块是吗？我再送给你两只各100ml的shampoo，还有12条shampoo，一条8ml，送你的将近是300ml，一只是正装400ml，我送你差不多要一罐了啊，going是吧，如果你也是油头一天不洗头也是非常油的话呢，你就点击视频的左下角链接去购买哟，真的有效，你会喜欢的。", "ai_analysis_tags": [ "#shampoo", "#conditioner", "#haircare", "#oilyhair", "#amaxy", "#hairproduct", "#hair", "#beauty" ], "ai_analysis_language": "zh-cn", "ai_analysis_human_presenter": "yes", "had_ai_analysis": true, "min_cpm": 33.74, "min_cpa": 1.0, "unique_id": "hows.sis" } ], "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 | 未授权 - API 密钥无效 | | 500 | 服务器内部错误 |