广告库列表接口

接口信息

• 接口名称: 广告库列表查询
• 请求方法: POST
• 接口地址: /open-api/v1/data
• 接口路径: /v3/api/open/lib-ads/list
• 接口描述: 获取广告库列表数据,支持多维度筛选条件和分页查询,适用于广告分析、竞品调研、素材挖掘等场景
• 价格说明: 获取一条数据结果消耗1 credit

请求头:

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

请求参数

请求结构

请求体参数 (params 对象)

基础参数

广告基础筛选

广告时间筛选

广告天数筛选

广告数据筛选

广告主筛选

按钮筛选

媒体素材筛选

受众筛选

落地页筛选

电商平台筛选

产品筛选

店铺筛选

App 筛选

关键词搜索

排除筛选

高级选项

请求示例

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

响应参数

响应体结构

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

响应字段说明

分页信息字段

首次广告日期统计字段 (ad_started_at_group)

当请求中设置了with_ad_started_at_group时,响应中会包含此字段：

广告状态统计字段 (ad_status_group)

当请求中设置了with_ad_status_group时,响应中会包含此字段：

广告信息字段 (data)

广告受众信息字段 (ad_audience)

受众年龄段字段 (age_audience)

受众国家明细字段 (details)

年龄性别细分字段 (age_gender_breakdowns)

广告主信息字段 (advertiser)

轮播图信息字段 (cards)

图片信息字段 (images)

视频信息字段 (videos)

产品信息字段 (products)

店铺信息字段 (store)

响应示例

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

错误码说明

注意事项

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等