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 格式:
[
{
"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产品进行搜索
请求示例
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
}
}'
响应参数
响应体结构
{
"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 |
是否有下一页 |
响应示例
{
"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 |
服务器内部错误 |