Pipispy APIEnglish

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

广告库产品详情接口

接口信息

  • 接口名称: 广告库产品详情
  • 请求方法: POST
  • 接口地址: /open-api/v1/data
  • 接口路径: /v3/api/open/ppspy/ad-products/detail
  • 接口描述: 根据产品ID获取广告库产品的详细信息,包括产品基本信息、广告数据、店铺信息、广告主信息以及广告数量趋势等完整数据
  • 价格说明: 基础费用:1 credit/次。 免费访问条件(满足其一即可): 该ID在3天内已获取过详情;该ID在3天内出现在您的榜单列表查询结果中。

请求头:

  • Content-Type: application/json
  • Accept: application/json

请求参数

请求结构

参数名 类型 描述 示例 必填 默认值
key string 用户申请的外部 api 请求 key "your_api_key_here" 是
uri string 接口路径 "/v3/api/open/ppspy/ad-products/detail" 是
params object 接口入参对象 见参数列表 是

路径参数

参数名 类型 必填 描述
id String 是 产品ID,用于标识要查询的具体产品。可以从产品搜索接口的返回结果中获取

请求示例

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/ppspy/ad-products/detail",
    "params": {
      "id": "5b9ac27f7b3d21aecdca5cb00be71baa"
    }
  }'

响应参数

响应体结构

{
  "code": 200,
  "message": "success",
  "data": {
    "product": {},
    "store": {},
    "advertisers": [],
    "ad_started_history": []
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 1,
  "success": true,
  "fail": false
}

响应字段说明

字段名 类型 描述
code Integer 业务状态码,200 表示成功
message String 响应的消息,成功时通常为"success"
data Object 响应的数据对象
version string API 版本
timestamp number 响应时间戳
sign string 响应签名
remaining_credits Long 当前请求后的剩余可用积分
consumed_credits Long 本次请求消耗的积分
success boolean 请求是否成功
fail boolean 请求是否失败

数据对象字段 (data)

字段名 类型 描述
product Object 产品信息,包含产品的完整详细数据
store Object 店铺信息,产品所属店铺的详细信息
advertisers Array 广告主信息列表,投放该产品广告的所有广告主数据
ad_started_history Array 广告数量的趋势,展示产品广告投放的历史趋势数据

产品信息字段 (product)

基本信息

字段名 类型 描述
id String 产品ID,产品的唯一标识符
name String 产品名称
price Double 产品价格(原始货币)
price_usd Double 产品美元价格,统一换算为美元方便比较
currency String 货币单位,如USD、EUR等
image_url String 产品主图URL,产品的主要展示图片
images String Array 产品图片列表,包含产品的所有图片URL
source_product_id String 电商平台的产品ID,在原电商平台的产品标识
source_product_link String 产品链接,产品在电商平台的详情页URL
e_commerce_platform String 电商平台,产品所在的电商平台名称
store_id String 店铺ID,产品所属店铺的唯一标识
category_id String 分类ID,产品所属分类的唯一标识
category_name String 分类名称,产品所属的分类名称
creation_time Long 产品创建时间,时间戳:秒
user_collected Integer 是否已收藏,可选值:
• 1 - 未收藏
• 2 - 已收藏

广告数据

字段名 类型 描述
ad_status Integer 广告状态,可选值:1-活跃中,2-已停止
ad_forecast Integer AI分数,可选值:1-测品阶段,2-上升阶段,3-盈利阶段
active_ad_count Integer 活跃广告数,当前正在投放的广告数量
ad_count Integer 广告数,产品总共创建的广告数量
active_adset_count Integer 活跃广告组数,当前正在投放的广告组数量
adset_count Integer 总广告组数,产品总共创建的广告组数量
adset_count_24h Integer 24小时广告组数,最近24小时内新增的广告组数量
active_days Integer 广告天数,产品持续投放广告的天数
ad_started_at Long 广告开始时间,时间戳:秒。产品首次开始投放广告的时间
ad_ended_at Long 广告结束时间,时间戳:秒。产品最后一次广告投放的结束时间
ad_cost Double 广告花费,单位:美元。产品累计的广告投入成本
ad_audience_reach Integer 覆盖人数,广告触达的独立用户总数
ad_platform String Array 广告平台列表,产品投放广告的平台,如FACEBOOK、INSTAGRAM等

店铺信息字段 (store)

字段名 类型 描述
id String 店铺ID,店铺的唯一标识符
name String 店铺名称
logo_url String 店铺logo图片URL
e_commerce_platform String 电商平台,店铺所在的电商平台名称
source_store_link String 店铺链接,店铺在电商平台的主页URL
month_visits Integer 月访问量,店铺的月度访问量(预估值)
published_products_count Integer 产品数量,店铺发布的产品总数
monthly_sales Integer 月销量,店铺的月度销售数量(预估值)

广告主信息字段 (advertisers)

advertisers 是一个数组,包含投放该产品广告的所有广告主信息。每个广告主对象包含以下字段:

基本信息

字段名 类型 描述
id String 广告主ID,广告主的唯一标识符
name String 广告主的名字
profile_picture_url String 广告主头像链接
source_advertiser_id String 广告主的主页ID,在广告平台上的主页标识
source_advertiser_link String 广告主的主页链接,广告主在广告平台的主页URL
ads_library_link String 广告主的广告库链接,查看该广告主所有广告的链接
category_name String 分类,广告主所属的分类
creation_time Long 创建时间,时间戳:秒

广告数据

字段名 类型 描述
ad_status Integer 广告状态,可选值:1-活跃中,2-已停止
active_ad_count Integer 活跃的广告数,该广告主当前正在投放的广告数量
inactive_ad_count Integer 不活跃的广告数,已暂停投放的广告数量
removed_ad_count Integer 已下架的广告数,已删除或下架的广告数量
ad_count Integer 广告素材数,该广告主总共创建的广告数量
adset_count Integer 广告组数,该广告主创建的广告组总数
active_days Integer 广告天数,该广告主持续投放广告的天数
ad_started_at Long 广告开始时间,时间戳:秒
ad_ended_at Long 广告结束时间,时间戳:秒
ad_country String Array 投放国家列表,该广告主广告投放的国家代码
ad_platform String Array 广告平台列表,该广告主使用的广告平台
like_count Integer 点赞数,该广告主广告获得的点赞总数
ad_source Integer 广告来源

广告趋势数据字段 (ad_started_history)

ad_started_history 是一个数组,记录产品广告数量随时间的变化趋势。每个趋势数据点包含以下字段:

字段名 类型 描述
date String 日期,UTC时间。格式:YYYY-MM-DD
count Integer 广告数,该日期对应的广告数量

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "advertisers": [
      {
        "id": "f57f4c9d3ea20be66a132adb5f557eba",
        "name": "wijnvoordeel.be",
        "active_ad_count": 9,
        "active_days": 780,
        "ad_count": 321,
        "ad_country": [
          "BE",
          "other"
        ],
        "ad_ended_at": 1766995200,
        "ad_started_at": 1699603200,
        "ad_status": 1,
        "ads_library_link": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=ALL&is_targeted_country=false&media_type=all&search_type=page&view_all_page_id=186022184808923",
        "adset_count": 531,
        "creation_time": 1318448479,
        "inactive_ad_count": 0,
        "like_count": 19420,
        "profile_picture_url": "https://scontent-lga3-1.xx.fbcdn.net/v/t39.35426-6/599566144_1210304384349710_4804416712767355916_n.jpg?stp=dst-jpg_s60x60_tt6&_nc_cat=111&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=UydCX9qVwIMQ7kNvwGqJ0kM&_nc_oc=AdnRT5BJoxS5kk-6exgTkCsIjeAeP4S6lmunXkvWZZOS6QNPr_cXeohqsKL1RegXxU4&_nc_zt=14&_nc_ht=scontent-lga3-1.xx&_nc_gid=lEhGO0OMT5L5L9xSpwx3OA&oh=00_AfnI22FlLJw3cHbRiXqUAIQRp1pSWWmgsYlAgNt9RC5y3Q&oe=69592A57",
        "removed_ad_count": 312,
        "ad_source": 1,
        "category_name": "Wine, Beer & Spirits Store",
        "source_advertiser_id": "186022184808923",
        "source_advertiser_link": "https://facebook.com/WijnvoordeelBE"
      }
    ],
    "product": {
      "currency": "EUR",
      "id": "5b9ac27f7b3d21aecdca5cb00be71baa",
      "images": [
        "https://fb-cdn.ppspy.com/images/pimg_c1cb26db9e59ba4c70688.png",
        "https://fb-cdn.ppspy.com/images/pimg_6ca311198854c6eeeffc9.png",
        "https://fb-cdn.ppspy.com/images/pimg_0d9e6a0a2e72f9f291f07.png",
        "https://fb-cdn.ppspy.com/images/pimg_c1cb26db9e59ba4c70688.png",
        "https://fb-cdn.ppspy.com/images/pimg_6ca311198854c6eeeffc9.png"
      ],
      "name": "Infinitum Grillo",
      "price": 5.79,
      "active_ad_count": 1,
      "active_adset_count": 1,
      "active_days": 2,
      "ad_audience_reach": 368,
      "ad_cost": 6.6,
      "ad_count": 1,
      "ad_ended_at": 1766995200,
      "ad_forecast": 1,
      "ad_started_at": 1766822400,
      "ad_status": 1,
      "adset_count": 1,
      "adset_count_24h": 0,
      "category_id": "62739aec38365b2f72048ebd",
      "ad_platform": [
        "FACEBOOK",
        "INSTAGRAM",
        "MESSENGER",
        "THREADS"
      ],
      "category_name": "Food",
      "e_commerce_platform": "magento",
      "price_usd": 6.82,
      "source_product_id": "c068345331a01d1216591db170f03672",
      "image_url": "https://fb-cdn.ppspy.com/images/pimg_c1cb26db9e59ba4c70688.png",
      "source_product_link": "https://www.wijnvoordeel.be/infinitum-grillo?channable=019969736b75004b3230303738324e",
      "store_id": "2382cd09c06c7d31cdca5cb00be71baa",
      "user_collected": 2
    },
    "store": {
      "id": "2382cd09c06c7d31cdca5cb00be71baa",
      "name": "wijnvoordeel.be",
      "e_commerce_platform": "magento",
      "logo_url": "https://fb-cdn.pipiads.com/icon_ad0a30d8c8334ccbf37488a8ce91377b.png",
      "month_visits": 19928,
      "source_store_link": "http://wijnvoordeel.be"
    },
    "ad_started_history": [
      {
        "count": 1,
        "date": "2025-12-27"
      }
    ]
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 1,
  "success": true,
  "fail": false
}

错误码说明

错误码 描述
200 成功
400 请求参数错误,产品ID格式不正确
401 未授权,API key无效或已过期
403 权限不足,账户余额不足或接口访问受限
404 产品不存在,找不到指定ID的产品
444 请求过于频繁,已触发限流
500 服务器内部错误,请稍后重试

注意事项

  1. 产品ID获取: 产品ID需要从广告产品搜索接口 (/v3/api/open/ppspy/ad-products/search) 的返回结果中获取
  2. 数据完整性: 某些字段可能为null,表示该数据暂未收集或不适用于该产品
  3. 广告主数量: advertisers 数组可能包含多个广告主,表示有多个广告主在推广同一个产品
  4. 趋势数据: ad_started_history 提供了时间序列数据,可用于绘制趋势图表
  5. 时间格式:
    • 产品和广告主的时间字段使用Unix时间戳(秒级)
    • 趋势数据的日期使用UTC时间,格式为 YYYY-MM-DD
  6. 货币单位: 所有价格相关字段(price、price_usd、ad_cost)的单位可能不同,注意区分
  7. 广告平台: ad_platform 字段可能包含多个平台,如FACEBOOK、INSTAGRAM、AUDIENCE_NETWORK、MESSENGER等
  8. 分类信息: 产品和广告主可能属于不同的分类,category_id 和 category_name 分别对应产品和广告主的分类
  9. 数据更新: 广告数据会定期更新,建议定期重新查询以获取最新数据
  10. 收藏状态: user_collected 字段反映当前API用户的收藏状态,不同用户查询同一产品可能返回不同值