广告库产品搜索接口

接口信息

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

请求头:

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

请求参数

请求结构

请求体参数 (params 对象)

基础参数

产品筛选参数

产品价格筛选

产品时间筛选

广告数据筛选

广告时间筛选

广告天数筛选

广告素材筛选

广告组数筛选

广告花费筛选

覆盖人数筛选

店铺筛选参数

店铺产品数筛选

店铺广告数据筛选

关键词搜索

请求示例

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
    }
  }'

响应参数

响应体结构

{
  "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
}

响应字段说明

分页信息字段

产品信息字段

产品广告数据字段

店铺信息字段 (store)

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

响应示例

{
  "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
}

错误码说明

注意事项

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. 数据更新: 广告数据会定期更新，建议定期重新查询以获取最新数据