Pipispy APIEnglish

数据消耗规则:1. 获取一条数据结果消耗1 数据,获取数据结果的更多数据详情不消耗数据。2. 广告监控: 每次监控 $1 / 月。单个监控有效期为一个月,一个月后自动停止。删除监控不会恢复监控次数,请谨慎删除。监控调用为随时且无限次。

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
字段名 类型 描述
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 服务器内部错误