# 广告库列表接口
## 接口信息
- **接口名称**: 广告库列表查询
- **请求方法**: POST
- **接口地址**: `/open-api/v1/data`
- **接口路径**: `/v3/api/open/lib-ads/list`
- **接口描述**: 获取广告库列表数据,支持多维度筛选条件和分页查询,适用于广告分析、竞品调研、素材挖掘等场景
- **价格说明**: 获取一条数据结果消耗1 credit
**请求头:**
- Content-Type: application/json
- Accept: application/json
## 请求参数
### 请求结构
| 参数名 | 类型 | 描述 | 示例 | 必填 | 默认值 |
| ------ | ------ | --------------------------- | ---------------------------------- | ---- | ------ |
| key | string | 用户申请的外部 api 请求 key | "your_api_key_here" | 是 | |
| uri | string | 接口路径 | "/v3/api/open/lib-ads/list" | 是 | |
| params | object | 接口入参对象 | 见参数列表 | 是 | |
### 请求体参数 (params 对象)
#### 基础参数
| 参数名 | 类型 | 必填 | 描述 |
| --------- | ------- | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| page | Integer | 否 | 页码,最小值等于1。用于分页查询,指定要获取第几页的数据 |
| per_page | Integer | 否 | 分页大小,取值范围1-100。指定每页返回的广告数量 |
| order_by | String | 否 | 排序字段,决定按哪个指标对结果进行排序。可选值：
• ad_started_at - 广告创建时间
• first_discovered_at - 广告入库时间
• last_discovered_at - 广告最后更新时间
• latest_actived_at - 广告最后活跃时间
• active_days - 广告天数
• ad_cost - 广告花费
• ad_audience_reach - 覆盖人数
• adset_count - 广告组数
• advertiser_ad_count - 广告主广告素材数
• product_ad_count - 产品广告素材数
• product_price_usd - 产品价格
• product_creation_time - 产品创建时间
• store_ad_count - 店铺广告素材数
• video_duration - 视频时长
• app_last_month_download_count - App月安装量
• app_last_month_revenue_usd - App美元月收入
• app_rate_score - APP评分
• app_creation_time - App发布日期 |
| direction | String | 否 | 排序方式,与order_by配合使用。可选值：
• desc - 降序（从大到小）
• asc - 升序（从小到大） |
#### 广告基础筛选
| 参数名 | 类型 | 必填 | 描述 |
| ------------------ | ------ | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ad_content | String | 否 | 广告文案,用于搜索包含特定文案内容的广告 |
| ad_content_md5 | String | 否 | 广告文案的MD5,用于精准匹配相同文案的广告 |
| ad_platform | String | 否 | 广告平台,用于筛选在特定平台投放的广告。可选值：FACEBOOK、INSTAGRAM、AUDIENCE_NETWORK、MESSENGER、THREADS |
| ad_status | String | 否 | 广告状态,用于筛选不同投放状态的广告。可选值：
• 1 - 活跃（正在投放）
• 2 - 不活跃（已暂停）
• 3 - 下架（已停止） |
| ad_forecast | Long | 否 | 广告预测,基于AI算法评估广告所处阶段。可选值：
• 1 - Testing（测试阶段）
• 2 - Scaling（扩量阶段）
• 3 - Winning（盈利阶段） |
| country | String | 否 | 国家,用于筛选在特定国家投放的广告。使用ISO 3166-1 alpha-2标准的国家代码,多个国家用英文逗号分隔。示例："US,CA,GB" |
| language | String | 否 | 语言,用于筛选使用特定语言的广告。使用ISO 639-1标准的语言代码。示例："en" |
| data_type | String | 否 | 广告类型（大分类）,多个可以用英文逗号分隔。可选值：
• 1 - E-commerce（电商）
• 2 - Dropshipping（爆品跟卖）
• 3 - Games（游戏）
• 4 - App
• 5 - AI
• 6 - 短剧 |
| source_ad_id | String | 否 | 广告创意id,多个用英文逗号分隔。示例："3617279838571920,6767880647973308" |
| source_advertiser_id | String | 否 | 主页id,用于查询特定广告主的所有广告 |
#### 广告时间筛选
| 参数名 | 类型 | 必填 | 描述 |
| -------------------------- | ---- | ---- | ------------------------------------------------------------------------------------ |
| ad_started_at_start | Long | 否 | 广告创建时间（起）,时间戳：秒。用于筛选广告创建时间范围的下限 |
| ad_started_at_end | Long | 否 | 广告创建时间（止）,时间戳：秒。用于筛选广告创建时间范围的上限。与ad_started_at_start配合使用 |
| first_discovered_at_start | Long | 否 | 广告入库时间（起）,时间戳：秒。用于筛选广告入库时间范围的下限 |
| first_discovered_at_end | Long | 否 | 广告入库时间（止）,时间戳：秒。用于筛选广告入库时间范围的上限。与first_discovered_at_start配合使用 |
| last_discovered_at_start | Long | 否 | 广告最后更新时间（起）,时间戳：秒。用于筛选广告最后更新时间范围的下限 |
| last_discovered_at_end | Long | 否 | 广告最后更新时间（止）,时间戳：秒。用于筛选广告最后更新时间范围的上限。与last_discovered_at_start配合使用 |
| latest_actived_at_start | Long | 否 | 广告最后活跃时间（起）,时间戳：秒。用于筛选广告最后活跃时间范围的下限 |
| latest_actived_at_end | Long | 否 | 广告最后活跃时间（止）,时间戳：秒。用于筛选广告最后活跃时间范围的上限。与latest_actived_at_start配合使用 |
#### 广告天数筛选
| 参数名 | 类型 | 必填 | 描述 |
| ----------------- | ---- | ---- | -------------------------------------------------------------------------- |
| active_days_start | Long | 否 | 广告时长（起）,用于筛选广告投放天数范围的下限。天数越多说明广告持续投放时间越长 |
| active_days_end | Long | 否 | 广告时长（止）,用于筛选广告投放天数范围的上限。与active_days_start配合使用 |
#### 广告数据筛选
| 参数名 | 类型 | 必填 | 描述 |
| ----------------------- | ------- | ---- | -------------------------------------------------------------------------------------- |
| ad_audience_reach_start | Integer | 否 | reach（起）,用于筛选广告触达人数范围的下限。Reach指广告触达的独立用户数量 |
| ad_audience_reach_end | Integer | 否 | reach（止）,用于筛选广告触达人数范围的上限。与ad_audience_reach_start配合使用 |
| ad_cost_start | Double | 否 | 广告花费（起）,单位：美元。用于筛选广告花费金额范围的下限 |
| ad_cost_end | Double | 否 | 广告花费（止）,单位：美元。用于筛选广告花费金额范围的上限。与ad_cost_start配合使用 |
| adset_count_start | Long | 否 | 广告组数（起）,用于筛选广告组数量范围的下限 |
| adset_count_end | Long | 否 | 广告组数（止）,用于筛选广告组数量范围的上限。与adset_count_start配合使用 |
#### 广告主筛选
| 参数名 | 类型 | 必填 | 描述 |
| --------------------------- | ------ | ---- | -------------------------------------------------------------------------------------- |
| advertiser_id | String | 否 | 广告主ID,用于查询特定广告主的所有广告 |
| advertiser_name | String | 否 | 主页名字,用于搜索包含特定名称的广告主 |
| advertiser_ad_count_start | Long | 否 | 广告主广告素材数（起）,用于筛选广告主素材数量范围的下限 |
| advertiser_ad_count_end | Long | 否 | 广告主广告素材数（止）,用于筛选广告主素材数量范围的上限。与advertiser_ad_count_start配合使用 |
| with_blockded_advertiser | String | 否 | 返回用户屏蔽的广告主,用于控制是否在结果中包含被屏蔽的广告主 |
#### 按钮筛选
| 参数名 | 类型 | 必填 | 描述 |
| ----------- | ------ | ---- |-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| button_text | String | 否 | 按钮文本,用于搜索包含特定按钮文字的广告, 可取值有：
• Apply now
• Book now
• Buy tickets
• Contact us
• Donate now
• Download
• Get offer
• Get quote
• Get showtimes
• Send message
• Install now
• Learn more
• No button
• Order now
• Play game
• Request time
• See menu
• Shop now
• Sign up
• Subscribe
• Watch more |
| button_type | String | 否 | 按钮类型,用于筛选使用特定行动号召按钮类型的广告,可取值有：
• APPLY_NOW
• BOOK_TRAVEL
• BUY_TICKETS
• CONTACT_US
• DONATE_NOW
• DOWNLOAD
• GET_OFFER
• GET_OFFER_VIEW
• GET_QUOTE
• GET_SHOWTIMES
• INSTAGRAM_MESSAGE
• INSTALL_MOBILE_APP
• LEARN_MORE
• NO_BUTTON
• ORDER_NOW
• PLAY_GAME
• REQUEST_TIME
• SEE_MENU
• SHOP_NOW
• SIGN_UP
• SUBSCRIBE
• WATCH_MORE |
#### 媒体素材筛选
| 参数名 | 类型 | 必填 | 描述 |
| ------------------ | ------ | ---- | -------------------------------------------------------------------------------------------------------------- |
| media_format | String | 否 | 媒体格式,用于筛选特定素材格式的广告。可选值：
• 1 - 视频
• 2 - 图片
• 3 - 轮播图 |
| video_duration_start | Long | 否 | 视频时长（起）,单位：秒。用于筛选视频时长范围的下限 |
| video_duration_end | Long | 否 | 视频时长（止）,单位：秒。用于筛选视频时长范围的上限。与video_duration_start配合使用 |
| size | String | 否 | 尺寸比例,多个可以用英文逗号分隔。用于筛选特定尺寸比例的广告素材 |
| aspect_ratio | String | 否 | 分辨率,多个可以用英文逗号分隔。用于筛选特定宽高比的广告素材 |
| clarity | String | 否 | 画质,多个可以用英文逗号分隔。可选值：
• HD - 高清
• SD - 标清
• LD - 低清
• UNKNOWN - 未知 |
#### 受众筛选
| 参数名 | 类型 | 必填 | 描述 |
| --------------- | ------ | ---- | ---------------------------------------------------------------------------------------------- |
| gender_audience | String | 否 | 性别,多个可以用英文逗号分隔。可选值：
• All - 全部
• Men - 男性
• Women - 女性 |
| age_audience | String | 否 | 年龄,多个可以用英文逗号分隔。用于筛选特定年龄段的广告受众 |
#### 落地页筛选
| 参数名 | 类型 | 必填 | 描述 |
| ----------------- | ------ | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| landing_pages | String | 否 | 落地页URL,用于搜索包含特定落地页链接的广告 |
| landing_pages_md5 | String | 否 | 落地页的MD5,用于精准匹配相同落地页的广告 |
| landing_page_type | String | 否 | 落地页面属性,用于筛选特定类型落地页的广告。可选值：
• 1 - 电商的产品
• 2 - 电商的Collection Pages
• 3 - 电商的其它
• 4 - APP
• 5 - AI网站
• 6 - 短剧网站
• 100 - 其它
• 101 - 有重定向链接（暂不支持,预留） |
| related_roots | String | 否 | 域名,多个可以用英文逗号分隔。用于筛选特定域名下的广告 |
#### 电商平台筛选
| 参数名 | 类型 | 必填 | 描述 |
| ------------------- | ------ | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| e_commerce_platform | String | 否 | 电商平台,用于筛选来自特定电商平台的广告。可选值：
• shopify
• woocommerce
• magento
• prestashop
• opencart
• bigcommerce
• ecwid
• shopline
• shoplazza
• wix
• squarespace |
| e_commerce_type | String | 否 | 电商类型,多个可以用英文逗号分隔。可选值：
• 1 - Dropshipping
• 2 - Print on demand (POD)
• 3 - Cash/collect on delivery (COD)
• 4 - Digital products |
#### 产品筛选
| 参数名 | 类型 | 必填 | 描述 |
| --------------------------- | ------ | ---- | ------------------------------------------------------------------------------------------ |
| product_name | String | 否 | 产品名字,用于搜索包含特定产品名称的广告 |
| product_category_id | String | 否 | 产品分类,用于筛选特定品类的产品广告。见 [电商分类](https://www.pipispy.com/zh/doc/others-product-category) |
| product_price_usd_start | Double | 否 | 产品价格（起）,单位：美元。用于筛选产品价格范围的下限 |
| product_price_usd_end | Double | 否 | 产品价格（止）,单位：美元。用于筛选产品价格范围的上限。与product_price_usd_start配合使用 |
| product_creation_time_start | Long | 否 | 产品创建时间（起）,时间戳：秒。用于筛选产品创建时间范围的下限 |
| product_creation_time_end | Long | 否 | 产品创建时间（止）,时间戳：秒。用于筛选产品创建时间范围的上限。与product_creation_time_start配合使用 |
| product_ad_count_start | Long | 否 | 产品广告素材数（起）,用于筛选产品素材数量范围的下限 |
| product_ad_count_end | Long | 否 | 产品广告素材数（止）,用于筛选产品素材数量范围的上限。与product_ad_count_start配合使用 |
| related_product_ids | String | 否 | 产品 ID,多个用英文逗号分隔。用于批量查询指定产品的广告。示例："prod_1,prod_2" |
#### 店铺筛选
| 参数名 | 类型 | 必填 | 描述 |
| -------------------- | ------ | ---- | ---------------------------------------------------------------------------------- |
| store_ad_count_start | Long | 否 | 店铺广告素材数（起）,用于筛选店铺素材数量范围的下限 |
| store_ad_count_end | Long | 否 | 店铺广告素材数（止）,用于筛选店铺素材数量范围的上限。与store_ad_count_start配合使用 |
| related_store_ids | String | 否 | 店铺 ID,多个用英文逗号分隔。用于批量查询指定店铺的广告。示例："store_1,store_2" |
#### App 筛选
| 参数名 | 类型 | 必填 | 描述 |
| -------------------------------------- | ------ | ---- | ------------------------------------------------------------------------------------------------------------------------ |
| app_store | String | 否 | 应用平台,多个可以用英文逗号分隔。可选值：
• apple - 苹果应用商店
• google - 谷歌应用商店
• web - 网站 |
| app_category | String | 否 | App分类（沿用pipiads整理好的分类）,多个可以用英文逗号分隔。用于筛选特定类别的App广告 |
| app_ai_category | String | 否 | App的AI分类,多个可以用英文逗号分隔。基于AI算法对App进行的智能分类 |
| app_developer_ids | String | 否 | App开发者ID,多个可以用英文逗号分隔。用于查询特定开发者的所有App广告 |
| app_creation_time_start | Long | 否 | App发布日期（起）,时间戳：秒。用于筛选App发布时间范围的下限 |
| app_creation_time_end | Long | 否 | App发布日期（止）,时间戳：秒。用于筛选App发布时间范围的上限。与app_creation_time_start配合使用 |
| app_rate_score_start | Double | 否 | APP评分（起）,用于筛选App评分范围的下限。评分范围通常为0-5分 |
| app_rate_score_end | Double | 否 | APP评分（止）,用于筛选App评分范围的上限。与app_rate_score_start配合使用 |
| app_last_month_download_count_start | Long | 否 | App月安装量（起）,用于筛选App月度安装量范围的下限。指最近一个月的预估安装量 |
| app_last_month_download_count_end | Long | 否 | App月安装量（止）,用于筛选App月度安装量范围的上限。与app_last_month_download_count_start配合使用 |
| app_last_month_revenue_usd_start | Double | 否 | App美元月收入（起）,单位：美元。用于筛选App月度收入范围的下限。指最近一个月的预估收入 |
| app_last_month_revenue_usd_end | Double | 否 | App美元月收入（止）,单位：美元。用于筛选App月度收入范围的上限。与app_last_month_revenue_usd_start配合使用 |
#### 关键词搜索
| 参数名 | 类型 | 必填 | 描述 |
| ---------------- | ----- | ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| extend_keywords | Array | 否 | 关键词搜索列表,用于按关键词搜索广告。支持多个关键词组合搜索,数组中的每个对象包含以下字段：
• field - 搜索的字段,可选值：all（全部）、ad_content（广告文案）、landing_pages（广告落地页URL）、advertiser_name（广告主page 名字）、product_name（产品名字）、product（电商产品：产品名称、产品链接）、store（店铺：店铺名称、店铺链接）、app_name（App名字）、app_developer_name（开发者名字）、advertiser（Social page：广告主名称、源广告主ID）、material（素材信息：script/Hook/Tags,预留,暂时没有）
• logic_operator - 逻辑运算符,可选值：and（且）、or（或）
• value - 搜索的内容 |
| exclude_keywords | Array | 否 | 关键词（排除）列表,用于排除包含特定关键词的广告。结构与extend_keywords相同 |
#### 排除筛选
| 参数名 | 类型 | 必填 | 描述 |
| ---------------------- | ----- | ---- | -------------------------------------------------------- |
| exclude_ad_content | Array | 否 | 广告文案（排除）,用于排除包含特定文案的广告 |
| exclude_advertiser_id | String | 否 | 广告主ID（排除）,多个可以用英文逗号分隔。用于排除特定广告主的广告 |
| exclude_advertiser_name | Array | 否 | 广告主page 名字（排除）,用于排除包含特定名称的广告主 |
| exclude_landing_pages | Array | 否 | 落地页URL（排除）,用于排除包含特定落地页链接的广告 |
| exclude_product_name | Array | 否 | 产品名字（排除）,用于排除包含特定产品名称的广告 |
#### 高级选项
| 参数名 | 类型 | 必填 | 描述 |
| ----------------------- | ------- | ---- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| enable_token_search | Integer | 否 | 分词搜索开关,用于控制是否启用分词搜索功能。可选值：
• 0 - 关闭分词搜索,按完整词匹配
• 1 - 开启分词搜索,支持模糊匹配和部分词匹配 |
| release_area | String | 否 | 发布地区。可选值：
• 1 - 欧盟版 |
| search_after | String | 否 | 深度分页查询（兼容处理：如果需要使用该方式,第一页也传该参数,值为空字符串即可,&=search_after）
格式：[{排序字段的值}, {ID的值}] |
| with_ad_status_group | String | 否 | 返回各广告状态的广告数量,设置后响应数据中会包含ad_status_group字段,统计各状态下的广告数量 |
| with_ad_started_at_group | String | 否 | 返回首次广告日期的统计,设置后响应数据中会包含ad_started_at_group字段,按时间段统计广告数量（今日、昨日、近7天、近30天、近90天、全部） |
### 请求示例
```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/lib-ads/list",
"params": {
"page": 1,
"per_page": 20,
"ad_platform": "FACEBOOK",
"ad_status": "1",
"country": "US",
"ad_cost_start": 100,
"ad_cost_end": 1000,
"extend_keywords": [
{
"field": "ad_content",
"value": "sale",
"logic_operator": "and"
}
],
"order_by": "ad_started_at",
"direction": "desc",
"with_ad_status_group": "true"
}
}'
```
## 响应参数
### 响应体结构
```json
{
"code": 200,
"message": "success",
"data": {
"ad_started_at_group": {},
"ad_status_group": {},
"current_page": 1,
"data": [],
"first_page_url": "",
"from": 1,
"last_page": 10,
"last_page_url": "",
"next_page_url": "",
"path": "",
"per_page": 20,
"prev_page_url": "",
"to": 20,
"total": 200,
"search_after": [],
"has_more": false,
"is_manual_search": false
},
"version": "v1",
"timestamp": null,
"sign": null,
"remaining_credits": 9980,
"consumed_credits": 20,
"success": true,
"fail": false
}
```
### 响应字段说明
| 字段名 | 类型 | 描述 |
| --------- | ------- | ---------------------------- |
| code | Integer | 业务状态码,200 表示成功 |
| message | String | 响应的消息,成功时通常为"success" |
| data | Object | 响应的数据对象 |
| version | String | API 版本 |
| timestamp | Long | 响应时间戳 |
| sign | String | 响应签名 |
| remaining_credits | Long | 当前请求后的剩余可用积分 |
| consumed_credits | Long | 本次请求消耗的积分 |
| success | Boolean | 请求是否成功 |
| fail | Boolean | 请求是否失败 |
### 分页信息字段
| 字段名 | 类型 | 描述 |
| ----------------------- | ------- | ------------------------------------------------------------------------------------------ |
| ad_started_at_group | Object | 首次广告日期的统计,如果设置了with_ad_started_at_group才会返回 |
| ad_status_group | Object | 各广告状态的广告数量,如果设置了with_ad_status_group才会返回 |
| current_page | Integer | 当前页码 |
| data | Array | 广告数据列表,包含广告信息数组 |
| first_page_url | String | 第一页URL |
| from | Integer | 当前页起始记录数 |
| last_page | Integer | 最后一页的页码,可用于判断总页数 |
| last_page_url | String | 最后一页URL |
| next_page_url | String | 下一页URL |
| path | String | 分页路径 |
| per_page | Integer | 分页大小,每页返回的数据条数 |
| prev_page_url | String | 上一页URL |
| to | Integer | 当前页结束记录数 |
| total | Integer | 总数据量,满足筛选条件的广告总数 |
| search_after | Array | 深度分页的"标签",如果设置了search_after才会返回 |
| has_more | Boolean | 是否有更多,如果设置了search_after才会返回 |
| is_manual_search | Boolean | free用户是否更改过筛选项,true=有 |
### 首次广告日期统计字段 (ad_started_at_group)
当请求中设置了with_ad_started_at_group时,响应中会包含此字段：
| 字段名 | 类型 | 描述 |
| ------------- | ------- | -------- |
| today | Integer | 今日 |
| yesterday | Integer | 昨日 |
| last_7_days | Integer | 近7天 |
| last_30_days | Integer | 近30天 |
| last_90_days | Integer | 近90天 |
| total | Integer | 全部 |
### 广告状态统计字段 (ad_status_group)
当请求中设置了with_ad_status_group时,响应中会包含此字段：
| 字段名 | 类型 | 描述 |
| -------------- | ------- | ------ |
| ad_status_1 | Integer | 活跃 |
| ad_status_2 | Integer | 不活跃 |
| ad_status_3 | Integer | 下架 |
| ad_status_all | Integer | 全部 |
### 广告信息字段 (data)
| 字段名 | 类型 | 描述 |
| ------------------- | ------- | -------------------------------------- |
| id | String | 广告ID,系统内部唯一标识 |
| active_days | Long | 广告天数 |
| ad_audience | Object | 受众 |
| ad_audience_reach | Long | reach |
| ad_content | String | 广告文案 |
| ad_cost | Double | 广告花费 |
| ad_forecast | Long | 广告预测 |
| ad_platform | Array | 广告平台 |
| ad_started_at | Long | 广告的创建时间 |
| ad_status | Long | 活跃状态 |
| adset_count | Long | 广告组数 |
| advertiser | Object | 广告主 |
| button_type | String | 按钮类型 |
| button_text | String | 按钮文案 |
| cards | Array | 轮播图 |
| country | Array | 国家 |
| first_discovered_at | Long | 广告入库时间 |
| images | Array | 图片 |
| landing_page_type | Long | 落地页面属性 |
| landing_pages | Array | 落地页URL |
| language | String | 语言 |
| last_discovered_at | Long | 广告最后更新时间 |
| latest_actived_at | Long | 广告最后时间 |
| media_format | Long | 媒体格式 |
| products | Array | 广告产品 |
| source_ad_id | String | 源广告ID |
| store | Object | 广告店铺 |
| user_collected | Integer | 用户收藏的广告,1：是；2：否； |
| videos | Array | 视频 |
| related_roots | Array | 基于域名的广告主 |
| group_name | String | 收藏分组名称,用户收藏时的分组名称 |
| favorite_time | Long | 收藏时间,用户收藏该广告的时间戳 |
| store_id | String | 店铺ID,对应 store.pipiads_biz_id |
| root_path_id | String | root_path 对应的数据库ID |
| shop_id | String | TikTok小店ID,PPSPY数据为null |
| app_id | String | 应用ID,PPSPY数据为null |
### 广告受众信息字段 (ad_audience)
| 字段名 | 类型 | 描述 |
| --------------- | ------ | -------------- |
| age_audience | Object | 受众的年龄段 |
| details | Array | 受众国家明细 |
| gender_audience | String | 受众的群体 |
| total_reach | Long | 受众的总人数 |
### 受众年龄段字段 (age_audience)
| 字段名 | 类型 | 描述 |
| ------ | ---- | ---- |
| max | Long | 最大年龄 |
| min | Long | 最小年龄 |
### 受众国家明细字段 (details)
| 字段名 | 类型 | 描述 |
| --------------------- | ------ | ------------ |
| age_gender_breakdowns | Array | 受众明细 |
| country | String | 国家 |
| total_reach | Long | 受众的人数 |
### 年龄性别细分字段 (age_gender_breakdowns)
| 字段名 | 类型 | 描述 |
| --------- | ------ | ------------ |
| age_range | String | 年龄段 |
| female | Long | 女性的数量 |
| male | Long | 男性的数量 |
| unknown | Long | 其它的数量 |
### 广告主信息字段 (advertiser)
| 字段名 | 类型 | 描述 |
| ---------------------- | ------- | --------------------------------- |
| id | String | 广告主ID |
| name | String | 广告主page的名字 |
| ad_count | Long | 广告主page 素材数 |
| ad_country | Array | 投放国家 |
| ads_library_link | String | library链接 |
| adset_count | Long | 广告组数 |
| e_commerce_platform | String | 电商平台 |
| like_count | Long | 广告主page点赞数 |
| profile_picture_url | String | 广告主头像链接 |
| source_advertiser_id | String | 主页id |
| source_advertiser_link | String | 广告主的源链接 |
| user_blocked | Integer | 用户屏蔽的广告主,1：是；2：否； |
### 轮播图信息字段 (cards)
| 字段名 | 类型 | 描述 |
| ---------- | ------ | --------------------------- |
| cover_url | String | 视频的封面图链接 |
| duration | Long | 视频的时长 |
| height | Long | 视频/图片的高度 |
| media_type | Long | 媒体类型,1：视频；2：图片； |
| url | String | 视频/图片的链接 |
| width | Long | 视频/图片的宽度 |
### 图片信息字段 (images)
| 字段名 | 类型 | 描述 |
| ------ | ------ | ------------ |
| height | Long | 图片的高度 |
| url | String | 图片的链接 |
| width | Long | 图片的宽度 |
### 视频信息字段 (videos)
| 字段名 | 类型 | 描述 |
| --------- | ------ | ---------------- |
| cover_url | String | 视频的封面图链接 |
| duration | Long | 视频的时长 |
| height | Long | 视频的高度 |
| url | String | 视频的链接 |
| width | Long | 视频的宽度 |
### 产品信息字段 (products)
| 字段名 | 类型 | 描述 |
| ------------------- | ------ | ------------------------------- |
| id | String | 产品ID |
| name | String | 产品名字 |
| ad_cost | Double | 广告花费 |
| ad_cost_ratio | Double | 产品在这个广告的花费的比例,0~1 |
| ad_count | Long | 产品广告素材数 |
| ad_ended_at | Long | 广告结束时间 |
| ad_started_at | Long | 广告开始时间 |
| category_id | String | 分类ID |
| category_name | String | 分类名称 |
| creation_time | Long | 创建时间 |
| currency | String | 货币 |
| image_url | String | 产品图片 |
| price | Double | 产品价格 |
| price_usd | Double | 产品价格（美元） |
| source_product_link | String | 产品链接 |
| total_revenue | Double | 产品的收入 |
### 店铺信息字段 (store)
| 字段名 | 类型 | 描述 |
| ------------------- | ------- | ---------------- |
| id | String | 店铺ID |
| name | String | 店铺名称 |
| ad_count | Long | 店铺素材数 |
| e_commerce_platform | String | 电商平台 |
| e_commerce_types | Array | 电商类型 |
| logo_url | String | 店铺logo图片 |
| source_store_link | String | 店铺链接 |
| pipiads_biz_id | String | 皮皮中的店铺ID |
## 响应示例
```json
{
"code": 200,
"message": "success",
"data": {
"ad_started_at_group": {
"today": 10,
"yesterday": 25,
"last_7_days": 150,
"last_30_days": 500,
"last_90_days": 1200,
"total": 41166
},
"ad_status_group": {
"ad_status_1": 15000,
"ad_status_2": 20000,
"ad_status_3": 6166,
"ad_status_all": 41166
},
"current_page": 1,
"data": [
{
"id": "428822805b9d1826ae0486cb66311288",
"active_days": 1,
"ad_audience": {
"details": [
{
"country": "BE",
"age_gender_breakdowns": [
{
"female": 0,
"male": 1,
"unknown": 0,
"age_range": "25-34"
}
],
"total_reach": 2
}
],
"age_audience": {
"max": 65,
"min": 25
},
"gender_audience": "All",
"total_reach": 0
},
"ad_audience_reach": 0,
"ad_content": "No knife skills, no stress — just load, press, and boom, you've got sushi 🍱🙌",
"ad_cost": 1.37,
"ad_forecast": 1,
"ad_platform": [
"FACEBOOK",
"INSTAGRAM",
"AUDIENCE_NETWORK",
"MESSENGER",
"THREADS"
],
"ad_started_at": 1752130800,
"ad_status": 2,
"adset_count": 1,
"advertiser": {
"id": "c979c0120e4b6d5dae0486cb66311288",
"name": "Stumpf Alston Nicholas",
"ad_count": 643,
"ad_country": [
"SE",
"ES",
"BE",
"AT",
"DE",
"FR",
"IT",
"IE",
"PT",
"NL"
],
"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=127604557091989",
"adset_count": 1381,
"e_commerce_platform": "shopify",
"like_count": 7,
"profile_picture_url": "https://fb-cdn.pipispy.com/images/af109907042f563cd317a8a64ddce21e.png",
"source_advertiser_id": "127604557091989",
"source_advertiser_link": "https://facebook.com/61550723637932",
"user_blocked": 2
},
"button_text": "Shop now",
"button_type": "SHOP_NOW",
"cards": [],
"country": [
"BE",
"DE",
"GB",
"DK",
"FI",
"PT",
"SE",
"IE",
"IT",
"ES",
"AT"
],
"first_discovered_at": 1752188451,
"images": [],
"landing_page_type": 1,
"landing_pages": [
"https://counitty.com/products/ultimate-sushi-making-kit"
],
"language": "en",
"last_discovered_at": 1752188451,
"latest_actived_at": 1752130800,
"media_format": 1,
"products": [
{
"id": "b71e0551cfbb314175c4dac1b4cf2dfc",
"name": "🍣 Ultimate Sushi Making Kit | Fun for All Ages · Easy to Use · Dishwasher Safe 🎉",
"ad_count": 7,
"ad_cost": 15.52,
"ad_cost_ratio": 0.0883,
"ad_ended_at": 1752130800,
"ad_started_at": 1752130800,
"category_id": "62739b6038365b2f72048ec1",
"category_name": "Home & Garden",
"creation_time": 1752134135,
"currency": "GBP",
"image_url": "https://fb-cdn.pipispy.com/images/pimg_8372835ac9512990130d7.png",
"price": 17.0,
"price_usd": 23.1,
"source_product_link": "https://counitty.com/products/ultimate-sushi-making-kit"
}
],
"source_ad_id": "1489834018843759",
"store": {
"id": "7458071d08bd6c3c75c4dac1b4cf2dfc",
"name": "Community Nail Care CenterLTD",
"ad_count": 421,
"e_commerce_platform": "shopify",
"e_commerce_types": [1, 2],
"logo_url": "https://fb-cdn.pipispy.com/images/store_logo.png",
"source_store_link": "https://counitty.com",
"pipiads_biz_id": "biz_123456"
},
"user_collected": 2,
"videos": [
{
"duration": 21,
"height": 1280,
"url": "https://fb-cdn.pipispy.com/videos/63a2820717c43d00f1481d20af5d0b6d.mp4",
"width": 720,
"cover_url": "https://fb-cdn.pipispy.com/images/d38b7ac2a4d956e541d338d84b3d10ae.png"
}
],
"related_roots": [
"counitty.com"
],
"favorite_time": 0,
"group_name": null,
"store_id": "biz_123456",
"root_path_id": "root_123",
"shop_id": null,
"app_id": null
}
],
"first_page_url": "http://app.ppspy.com/v1/lib-ads/list?page=1",
"from": 1,
"last_page": 2059,
"last_page_url": "http://app.ppspy.com/v1/lib-ads/list?page=2059",
"next_page_url": "http://app.ppspy.com/v1/lib-ads/list?page=2",
"path": "http://app.ppspy.com/v1/lib-ads/list",
"per_page": 20,
"prev_page_url": null,
"to": 20,
"total": 41166,
"search_after": null,
"has_more": false,
"is_manual_search": false
},
"version": "v1",
"timestamp": null,
"sign": null,
"remaining_credits": 9980,
"consumed_credits": 20,
"success": true,
"fail": false
}
```
## 错误码说明
| 错误码 | 描述 |
| ------ | -------------------------------------- |
| 200 | 成功 |
| 400 | 请求参数错误,请检查参数格式和取值范围 |
| 401 | 未授权,API key无效或已过期 |
| 403 | 权限不足,账户余额不足或接口访问受限 |
| 404 | 接口路径不存在 |
| 444 | 请求过于频繁,已触发限流 |
| 500 | 服务器内部错误,请稍后重试 |
## 注意事项
1. **分页限制**: 建议每页数据量设置在20-100之间,过大的分页会影响响应速度
2. **时间格式**: 所有时间字段均使用Unix时间戳（秒级）,请注意转换
3. **数组参数**: 使用数组类型的筛选条件时,会返回满足数组中任一值的结果（OR逻辑）
4. **范围筛选**: 使用start和end配对参数时,必须保证start ≤ end
5. **关键词搜索**: extend_keywords 和 exclude_keywords 可以组合使用,先应用包含关键词筛选,再应用排除关键词筛选
6. **排序优化**: 建议指定order_by和direction参数,否则将使用默认排序（ad_started_at降序）
7. **深度分页**: 当数据量较大时,建议使用search_after参数进行深度分页,性能更优
8. **统计字段**: with_ad_status_group 和 with_ad_started_at_group 只影响响应中的统计数据,不影响data列表内容
9. **数据更新**: 广告数据会定期更新,建议定期重新查询以获取最新数据
10. **多值参数**: 部分字段支持用英文逗号分隔多个值,如country、ad_platform等
11. **关键词字段**: extend_keywords和exclude_keywords支持的field字段包括all、ad_content、landing_pages、advertiser_name、product_name、product、store、app_name、app_developer_name、advertiser、material等
12. **电商平台**: e_commerce_platform支持的平台包括shopify、woocommerce、magento、prestashop、opencart、bigcommerce、ecwid、shopline、shoplazza、wix、squarespace等