# 广告库产品搜索接口

## 接口信息

- **接口名称**: 广告库产品搜索
- **请求方法**: POST
- **接口地址**: `/open-api/v1/data`
- **接口路径**: `/v3/api/open/ppspy/ad-products/search`
- **接口描述**: 根据多种筛选条件搜索广告库产品，支持按产品属性、店铺信息、广告数据等维度进行精准查询，适用于电商产品分析、竞品调研等场景
- **价格说明**: 获取一条数据结果消耗1 credit

**请求头:**

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

## 请求参数

### 请求结构

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

### 请求体参数 (params 对象)

#### 基础参数

| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| page | Integer | 否 | 页码，最小值等于1。用于分页查询，指定要获取第几页的数据 |
| per_page | Integer | 否 | 分页大小，取值范围1-100。指定每页返回的产品数量 |
| order_by | String | 否 | 排序字段，决定按哪个指标对结果进行排序。可选值：<br>• ad_started_at - 广告开始时间<br>• ad_ended_at - 广告结束时间<br>• active_adset_count - 活跃广告组数<br>• adset_count_24h - 24小时广告组数<br>• adset_count - 总广告组数<br>• ad_count - 广告素材数<br>• store_active_adset_count - 店铺活跃广告组数<br>• creation_time - 产品创建时间<br>• ad_audience_reach - 覆盖人数<br>• ad_cost - 广告花费<br>• active_days - 广告天数 |
| direction | String | 否 | 排序方式，与order_by配合使用。可选值：<br>• desc - 降序（从大到小）<br>• asc - 升序（从小到大） |

#### 产品筛选参数

| 参数名 | 类型 | 必填 | 描述                                                                                                              |
| ------ | ---- | ---- |-----------------------------------------------------------------------------------------------------------------|
| ids | String Array | 否 | 产品ID列表，用于批量查询指定产品。示例：["05fcadd84113edd111628deae2a75553", "1edc9a26b55b66a411628deae2a75553"]                                                                   |
| category_id | String Array | 否 | 产品分类ID列表，见 [电商分类](https://www.pipispy.com/zh/doc/others-product-category) 用于筛选特定品类的产品。示例：["62739aec38365b2f72048ebd", "62739b6038365b2f72048ec1"] |
| currency | String Array | 否 | 货币单位列表，用于筛选使用特定货币的产品。示例：["USD", "EUR"]                                                                          |
| e_commerce_platform | String Array | 否 | 电商平台列表，用于筛选来自特定电商平台的产品。示例：["shopify", "woocommerce"]                                                            |

#### 产品价格筛选

| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| price_usd_start | Double | 否 | 产品美元价格（开始），用于筛选价格范围的下限，单位：美元 |
| price_usd_end | Double | 否 | 产品美元价格（结束），用于筛选价格范围的上限，单位：美元。与price_usd_start配合使用 |

#### 产品时间筛选

| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| creation_time_start | Long | 否 | 产品创建时间（开始），时间戳：秒。用于筛选创建时间范围的下限 |
| creation_time_end | Long | 否 | 产品创建时间（结束），时间戳：秒。用于筛选创建时间范围的上限。与creation_time_start配合使用 |

#### 广告数据筛选

| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| ad_status | Integer | 否 | 广告状态，用于筛选不同投放状态的产品。可选值：<br>• 1 - 活跃中（正在投放广告）<br>• 2 - 已停止（广告已暂停） |
| ad_forecast | Integer Array | 否 | AI分数，基于AI算法评估产品所处阶段。可选值：<br>• 1 - 测品阶段（新品测试期）<br>• 2 - 上升阶段（增长期）<br>• 3 - 盈利阶段（成熟期）<br>示例：[1, 2] |

#### 广告时间筛选

| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| ad_started_at_start | Long | 否 | 广告开始时间（开始），时间戳：秒。用于筛选广告开始时间范围的下限 |
| ad_started_at_end | Long | 否 | 广告开始时间（结束），时间戳：秒。用于筛选广告开始时间范围的上限。与ad_started_at_start配合使用 |
| ad_ended_at_start | Long | 否 | 广告结束时间（开始），时间戳：秒。用于筛选广告结束时间范围的下限 |
| ad_ended_at_end | Long | 否 | 广告结束时间（结束），时间戳：秒。用于筛选广告结束时间范围的上限。与ad_ended_at_start配合使用 |

#### 广告天数筛选

| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| active_days_start | Long | 否 | 广告天数（开始），用于筛选广告投放天数范围的下限。天数越多说明产品持续投放时间越长 |
| active_days_end | Long | 否 | 广告天数（结束），用于筛选广告投放天数范围的上限。与active_days_start配合使用 |

#### 广告素材筛选

| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| ad_count_start | Integer | 否 | 广告素材数（开始），用于筛选产品广告素材数量范围的下限。素材数越多说明推广力度越大 |
| ad_count_end | Integer | 否 | 广告素材数（结束），用于筛选产品广告素材数量范围的上限。与ad_count_start配合使用 |

#### 广告组数筛选

| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| active_adset_count_start | Integer | 否 | 活跃广告组数（开始），用于筛选当前活跃广告组数量范围的下限。活跃广告组指正在投放的广告组 |
| active_adset_count_end | Integer | 否 | 活跃广告组数（结束），用于筛选当前活跃广告组数量范围的上限。与active_adset_count_start配合使用 |
| adset_count_start | Integer | 否 | 总广告组数（开始），用于筛选总广告组数量范围的下限，包括活跃和停止的广告组 |
| adset_count_end | Integer | 否 | 总广告组数（结束），用于筛选总广告组数量范围的上限。与adset_count_start配合使用 |
| adset_count_24h_start | Integer | 否 | 24小时广告组数（开始），用于筛选最近24小时内新增广告组数量范围的下限。用于发现最新热门产品 |
| adset_count_24h_end | Integer | 否 | 24小时广告组数（结束），用于筛选最近24小时内新增广告组数量范围的上限。与adset_count_24h_start配合使用 |

#### 广告花费筛选

| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| ad_cost_start | Double | 否 | 广告花费（开始），单位：美元。用于筛选广告花费金额范围的下限，可评估产品推广投入 |
| ad_cost_end | Double | 否 | 广告花费（结束），单位：美元。用于筛选广告花费金额范围的上限。与ad_cost_start配合使用 |

#### 覆盖人数筛选

| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| ad_audience_reach_start | Integer | 否 | 覆盖人数（开始），用于筛选广告覆盖人数范围的下限。覆盖人数指广告触达的独立用户数量 |
| ad_audience_reach_end | Integer | 否 | 覆盖人数（结束），用于筛选广告覆盖人数范围的上限。与ad_audience_reach_start配合使用 |

#### 店铺筛选参数

| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| store_id | String | 否 | 店铺ID，用于查询特定店铺下的所有产品 |
| store_country | String Array | 否 | 店铺国家列表，用于筛选来自特定国家的店铺产品。使用ISO 3166-1 alpha-2标准的国家代码。示例：["US", "CA", "GB"] |
| store_language | String Array | 否 | 店铺语言列表，用于筛选使用特定语言的店铺产品。使用ISO 639-1标准的语言代码。示例：["en", "de", "fr"] |
| store_pixel_platforms | String Array | 否 | Pixel平台列表，用于筛选安装了特定追踪像素的店铺产品。可选值：snap、tiktok、pinterest。示例：["tiktok", "snap"] |

#### 店铺产品数筛选

| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| store_published_products_count_start | Integer | 否 | 店铺产品数（开始），用于筛选店铺总产品数量范围的下限。可评估店铺规模 |
| store_published_products_count_end | Integer | 否 | 店铺产品数（结束），用于筛选店铺总产品数量范围的上限。与store_published_products_count_start配合使用 |

#### 店铺广告数据筛选

| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| store_active_adset_count_start | Integer | 否 | 店铺活跃广告组数（开始），用于筛选店铺当前活跃广告组数量范围的下限。可评估店铺当前推广力度 |
| store_active_adset_count_end | Integer | 否 | 店铺活跃广告组数（结束），用于筛选店铺当前活跃广告组数量范围的上限。与store_active_adset_count_start配合使用 |
| store_ad_count_start | Integer | 否 | 店铺广告素材数（开始），用于筛选店铺总广告素材数量范围的下限 |
| store_ad_count_end | Integer | 否 | 店铺广告素材数（结束），用于筛选店铺总广告素材数量范围的上限。与store_ad_count_start配合使用 |

#### 关键词搜索

| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| extend_keywords | Array | 否 | 关键词搜索列表，用于按关键词搜索产品。支持多个关键词组合搜索，数组中的每个对象包含以下字段：<br>• field - 搜索的字段，可选值：all（全部）、product_name（产品名称）、product_link（产品URL）、advertiser_name（广告主名称）<br>• logic_operator - 逻辑运算符，可选值：and、or<br>• value - 搜索的内容 |
| exclude_keywords | Array | 否 | 排除关键字列表，用于排除包含特定关键词的产品。结构与extend_keywords相同 |

### 请求示例

```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/ppspy/ad-products/search",
    "params": {
      "e_commerce_platform": ["magento"],
      "category_id": ["62739aec38365b2f72048ebd"],
      "extend_keywords": [
        {
          "field": "all",
          "value": "Infinitum Grillo",
          "logic_operator": "and"
        }
      ],
      "order_by": "ad_started_at",
      "direction": "desc",
      "page": 1,
      "ad_started_at_start": 1727712000,
      "ad_started_at_end": 1767110399,
      "per_page": 20
    }
  }'
```

## 响应参数

### 响应体结构

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "current_page": 1,
    "data": [],
    "last_page": 10,
    "per_page": 20,
    "total": 200
  },
  "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 | number        | 响应时间戳               |
| sign | string        | 响应签名                 |
| remaining_credits | Long    | 当前请求后的剩余可用积分 |
| consumed_credits  | Long    | 本次请求消耗的积分 |
| success | boolean       | 请求是否成功             |
| fail | boolean       | 请求是否失败             |

### 分页信息字段

| 字段名 | 类型 | 描述 |
| ------ | ---- | ---- |
| current_page | Integer | 当前页码 |
| data | Array | 数据列表，包含产品信息数组 |
| last_page | Integer | 最后一页的页码，可用于判断总页数 |
| per_page | Integer | 分页大小，每页返回的数据条数 |
| total | Integer | 总数据量，满足筛选条件的产品总数 |

### 产品信息字段

| 字段名 | 类型 | 描述 |
| ------ | ---- | ---- |
| 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 | 电商平台，产品所在的电商平台名称 |
| creation_time | Long | 产品创建时间，时间戳：秒 |
| user_collected | Integer | 是否已收藏，可选值：<br>• 1 - 未收藏<br>• 2 - 已收藏 |

### 产品广告数据字段

| 字段名 | 类型 | 描述 |
| ------ | ---- | ---- |
| ad_status | Integer | 广告状态，产品当前的广告投放状态 |
| ad_forecast | Integer | 产品分数，AI评估的产品阶段评分 |
| 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 | 覆盖人数，广告触达的独立用户总数 |

### 店铺信息字段 (store)

当返回数据包含店铺信息时，store对象包含以下字段：

| 字段名 | 类型 | 描述 |
| ------ | ---- | ---- |
| id | String | 店铺ID，店铺的唯一标识符 |
| name | String | 店铺名称 |
| logo_url | String | 店铺logo，店铺的标识图片URL |
| country | String | 店铺国家，店铺注册或主要运营的国家 |
| source_store_link | String | 店铺链接，店铺在电商平台的主页URL |
| e_commerce_platform | String | 电商平台，店铺所在的电商平台名称 |
| e_commerce_types | Integer Array | 电商类型，店铺的经营类型标识 |
| ad_count | Integer | 店铺素材数，店铺总共创建的广告素材数量 |
| adset_count | Integer | 总广告组数，店铺总共创建的广告组数量 |
| monthly_sales | Integer | 月销量，店铺的月度销售数量（预估值） |

## 响应示例

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "current_page": 1,
    "data": [
      {
        "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,
        "currency": "EUR",
        "e_commerce_platform": "magento",
        "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"
        ],
        "image_url": "https://fb-cdn.ppspy.com/images/pimg_c1cb26db9e59ba4c70688.png",
        "name": "Infinitum Grillo",
        "price": 5.79,
        "price_usd": 6.82,
        "source_product_id": "c068345331a01d1216591db170f03672",
        "source_product_link": "https://www.wijnvoordeel.be/infinitum-grillo?channable=019969736b75004b3230303738324e",
        "store": {
          "ad_count": 14,
          "adset_count": 27,
          "e_commerce_platform": "magento",
          "id": "2382cd09c06c7d31cdca5cb00be71baa",
          "logo_url": "https://fb-cdn.pipiads.com/icon_ad0a30d8c8334ccbf37488a8ce91377b.png",
          "name": "wijnvoordeel.be",
          "source_store_link": "http://wijnvoordeel.be"
        },
        "store_id": "2382cd09c06c7d31cdca5cb00be71baa",
        "user_collected": 2,
        "favorite_time": 0,
        "ad_platform": [
          "FACEBOOK",
          "INSTAGRAM",
          "MESSENGER",
          "THREADS"
        ]
      }
    ],
    "first_page_url": "http://app-pre.ppspy.com/v1/ad-products/search?direction=desc&page=1&ad_started_at_end=1767110399&ad_started_at_start=1727712000&category_id%5B0%5D=62739aec38365b2f72048ebd&e_commerce_platform%5B0%5D=magento&extend_keywords%5B0%5D%5Bfield%5D=all&extend_keywords%5B0%5D%5Bvalue%5D=Infinitum%20Grillo&extend_keywords%5B0%5D%5Blogic_operator%5D=and&order_by=ad_started_at&per_page=20",
    "from": 1,
    "is_logged_in": true,
    "last_page": 1,
    "last_page_url": "http://app-pre.ppspy.com/v1/ad-products/search?direction=desc&page=1&ad_started_at_end=1767110399&ad_started_at_start=1727712000&category_id%5B0%5D=62739aec38365b2f72048ebd&e_commerce_platform%5B0%5D=magento&extend_keywords%5B0%5D%5Bfield%5D=all&extend_keywords%5B0%5D%5Bvalue%5D=Infinitum%20Grillo&extend_keywords%5B0%5D%5Blogic_operator%5D=and&order_by=ad_started_at&per_page=20",
    "path": "http://app-pre.ppspy.com/v1/ad-products/search",
    "per_page": 20,
    "to": 1,
    "total": 1
  },
  "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参数，否则将使用默认排序，可能影响结果的相关性
7. **店铺信息**: store字段可能为null，表示该产品暂无关联店铺信息
8. **数据更新**: 广告数据会定期更新，建议定期重新查询以获取最新数据