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