Ad Library Product Search API

API Information

• API Name: Ad Library Product Search
• Request Method: POST
• API Endpoint: /open-api/v1/data
• API Path: /v3/api/open/ppspy/ad-products/search
• API Description: Search ad library products based on multiple filtering conditions, supporting precise queries by product attributes, store information, advertising data, and other dimensions. Suitable for e-commerce product analysis, competitor research, and other scenarios
• Pricing: Retrieving one data result consumes 1 credit

Request Headers:

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

Request Parameters

Request Structure

Request Body Parameters (params object)

Basic Parameters

Product Filter Parameters

Product Price Filtering

Product Time Filtering

Advertising Data Filtering

Ad Time Filtering

Ad Days Filtering

Ad Creative Filtering

Ad Set Count Filtering

Ad Spend Filtering

Reach Filtering

Store Filter Parameters

Store Product Count Filtering

Store Advertising Data Filtering

Keyword Search

Request Example

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

Response Parameters

Response Structure

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

Response Field Descriptions

Pagination Information Fields

Product Information Fields

Product Advertising Data Fields

Store Information Fields (store)

When the returned data contains store information, the store object contains the following fields:

Response Example

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

Error Code Descriptions

Notes

1. Pagination Limit: It is recommended to set the page data size between 20-100, as excessively large pagination will affect response speed
2. Time Format: All time fields use Unix timestamps (second-level), please pay attention to conversion
3. Array Parameters: When using array-type filter conditions, results satisfying any value in the array will be returned (OR logic)
4. Range Filtering: When using paired start and end parameters, ensure start ≤ end
5. Keyword Search: extend_keywords and exclude_keywords can be used in combination, first applying include keyword filtering, then applying exclude keyword filtering
6. Sorting Optimization: It is recommended to specify order_by and direction parameters, otherwise default sorting will be used, which may affect result relevance
7. Store Information: The store field may be null, indicating that the product currently has no associated store information
8. Data Updates: Ad data is updated regularly, it is recommended to re-query periodically to get the latest data