# 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

| Parameter | Type   | Description                 | Example                           | Required | Default |
| --------- | ------ | --------------------------- | --------------------------------- | -------- | ------- |
| key       | string | External API request key    | "your_api_key_here"               | Yes      |         |
| uri       | string | API path                    | "/v3/api/open/ppspy/ad-products/search" | Yes      |         |
| params    | object | API input parameters object | See parameter list                | Yes      |         |

### Request Body Parameters (params object)

#### Basic Parameters

| Parameter | Type    | Required | Description |
| --------- | ------- | -------- | ----------- |
| page      | Integer | No       | Page number, minimum value equals 1. Used for paginated queries to specify which page of data to retrieve |
| per_page  | Integer | No       | Page size, value range 1-100. Specifies the number of products returned per page |
| order_by  | String  | No       | Sort field, determines which metric to sort results by. Options:<br>• ad_started_at - Ad start time<br>• ad_ended_at - Ad end time<br>• active_adset_count - Active ad set count<br>• adset_count_24h - 24-hour ad set count<br>• adset_count - Total ad set count<br>• ad_count - Ad creative count<br>• store_active_adset_count - Store active ad set count<br>• creation_time - Product creation time<br>• ad_audience_reach - Reach<br>• ad_cost - Ad spend<br>• active_days - Ad days |
| direction | String  | No       | Sort order, used with order_by. Options:<br>• desc - Descending (large to small)<br>• asc - Ascending (small to large) |

#### Product Filter Parameters

| Parameter           | Type         | Required | Description |
| ------------------- | ------------ | -------- | ----------- |
| ids                 | String Array | No       | Product ID list, used for batch querying specified products. Example: ["05fcadd84113edd111628deae2a75553", "1edc9a26b55b66a411628deae2a75553"] |
| category_id         | String Array | No       | Product category ID list, see [E-commerce Categories](https://www.pipispy.com/zh/doc/others-product-category) for filtering products in specific categories. Example: ["62739aec38365b2f72048ebd", "62739b6038365b2f72048ec1"] |
| currency            | String Array | No       | Currency unit list, used for filtering products using specific currencies. Example: ["USD", "EUR"] |
| e_commerce_platform | String Array | No       | E-commerce platform list, used for filtering products from specific e-commerce platforms. Example: ["shopify", "woocommerce"] |

#### Product Price Filtering

| Parameter       | Type   | Required | Description |
| --------------- | ------ | -------- | ----------- |
| price_usd_start | Double | No       | Product USD price (start), used for filtering the lower limit of price range, unit: USD |
| price_usd_end   | Double | No       | Product USD price (end), used for filtering the upper limit of price range, unit: USD. Used with price_usd_start |

#### Product Time Filtering

| Parameter           | Type | Required | Description |
| ------------------- | ---- | -------- | ----------- |
| creation_time_start | Long | No       | Product creation time (start), timestamp: seconds. Used for filtering the lower limit of creation time range |
| creation_time_end   | Long | No       | Product creation time (end), timestamp: seconds. Used for filtering the upper limit of creation time range. Used with creation_time_start |

#### Advertising Data Filtering

| Parameter   | Type          | Required | Description |
| ----------- | ------------- | -------- | ----------- |
| ad_status   | Integer       | No       | Ad status, used for filtering products with different placement statuses. Options:<br>• 1 - Active (currently placing ads)<br>• 2 - Stopped (ads paused) |
| ad_forecast | Integer Array | No       | AI score, evaluates product stage based on AI algorithm. Options:<br>• 1 - Testing phase (new product testing)<br>• 2 - Growth phase (growth period)<br>• 3 - Profit phase (maturity period)<br>Example: [1, 2] |

#### Ad Time Filtering

| Parameter           | Type | Required | Description |
| ------------------- | ---- | -------- | ----------- |
| ad_started_at_start | Long | No       | Ad start time (start), timestamp: seconds. Used for filtering the lower limit of ad start time range |
| ad_started_at_end   | Long | No       | Ad start time (end), timestamp: seconds. Used for filtering the upper limit of ad start time range. Used with ad_started_at_start |
| ad_ended_at_start   | Long | No       | Ad end time (start), timestamp: seconds. Used for filtering the lower limit of ad end time range |
| ad_ended_at_end     | Long | No       | Ad end time (end), timestamp: seconds. Used for filtering the upper limit of ad end time range. Used with ad_ended_at_start |

#### Ad Days Filtering

| Parameter         | Type | Required | Description |
| ----------------- | ---- | -------- | ----------- |
| active_days_start | Long | No       | Ad days (start), used for filtering the lower limit of ad placement days range. More days indicates longer continuous placement |
| active_days_end   | Long | No       | Ad days (end), used for filtering the upper limit of ad placement days range. Used with active_days_start |

#### Ad Creative Filtering

| Parameter      | Type    | Required | Description |
| -------------- | ------- | -------- | ----------- |
| ad_count_start | Integer | No       | Ad creative count (start), used for filtering the lower limit of product ad creative count range. More creatives indicates greater promotion effort |
| ad_count_end   | Integer | No       | Ad creative count (end), used for filtering the upper limit of product ad creative count range. Used with ad_count_start |

#### Ad Set Count Filtering

| Parameter                | Type    | Required | Description |
| ------------------------ | ------- | -------- | ----------- |
| active_adset_count_start | Integer | No       | Active ad set count (start), used for filtering the lower limit of current active ad set count range. Active ad sets are those currently being placed |
| active_adset_count_end   | Integer | No       | Active ad set count (end), used for filtering the upper limit of current active ad set count range. Used with active_adset_count_start |
| adset_count_start        | Integer | No       | Total ad set count (start), used for filtering the lower limit of total ad set count range, including active and stopped ad sets |
| adset_count_end          | Integer | No       | Total ad set count (end), used for filtering the upper limit of total ad set count range. Used with adset_count_start |
| adset_count_24h_start    | Integer | No       | 24-hour ad set count (start), used for filtering the lower limit of new ad sets in the last 24 hours. Used for discovering latest trending products |
| adset_count_24h_end      | Integer | No       | 24-hour ad set count (end), used for filtering the upper limit of new ad sets in the last 24 hours. Used with adset_count_24h_start |

#### Ad Spend Filtering

| Parameter      | Type   | Required | Description |
| -------------- | ------ | -------- | ----------- |
| ad_cost_start  | Double | No       | Ad spend (start), unit: USD. Used for filtering the lower limit of ad spend amount range, can evaluate product promotion investment |
| ad_cost_end    | Double | No       | Ad spend (end), unit: USD. Used for filtering the upper limit of ad spend amount range. Used with ad_cost_start |

#### Reach Filtering

| Parameter               | Type    | Required | Description |
| ----------------------- | ------- | -------- | ----------- |
| ad_audience_reach_start | Integer | No       | Reach (start), used for filtering the lower limit of ad reach range. Reach refers to the number of unique users reached by ads |
| ad_audience_reach_end   | Integer | No       | Reach (end), used for filtering the upper limit of ad reach range. Used with ad_audience_reach_start |

#### Store Filter Parameters

| Parameter             | Type         | Required | Description |
| --------------------- | ------------ | -------- | ----------- |
| store_id              | String       | No       | Store ID, used for querying all products under a specific store |
| store_country         | String Array | No       | Store country list, used for filtering store products from specific countries. Uses ISO 3166-1 alpha-2 standard country codes. Example: ["US", "CA", "GB"] |
| store_language        | String Array | No       | Store language list, used for filtering store products using specific languages. Uses ISO 639-1 standard language codes. Example: ["en", "de", "fr"] |
| store_pixel_platforms | String Array | No       | Pixel platform list, used for filtering store products with specific tracking pixels installed. Options: snap, tiktok, pinterest. Example: ["tiktok", "snap"] |

#### Store Product Count Filtering

| Parameter                            | Type    | Required | Description |
| ------------------------------------ | ------- | -------- | ----------- |
| store_published_products_count_start | Integer | No       | Store product count (start), used for filtering the lower limit of store total product count range. Can evaluate store scale |
| store_published_products_count_end   | Integer | No       | Store product count (end), used for filtering the upper limit of store total product count range. Used with store_published_products_count_start |

#### Store Advertising Data Filtering

| Parameter                        | Type    | Required | Description |
| -------------------------------- | ------- | -------- | ----------- |
| store_active_adset_count_start   | Integer | No       | Store active ad set count (start), used for filtering the lower limit of store current active ad set count range. Can evaluate store's current promotion effort |
| store_active_adset_count_end     | Integer | No       | Store active ad set count (end), used for filtering the upper limit of store current active ad set count range. Used with store_active_adset_count_start |
| store_ad_count_start             | Integer | No       | Store ad creative count (start), used for filtering the lower limit of store total ad creative count range |
| store_ad_count_end               | Integer | No       | Store ad creative count (end), used for filtering the upper limit of store total ad creative count range. Used with store_ad_count_start |

#### Keyword Search

| Parameter        | Type  | Required | Description |
| ---------------- | ----- | -------- | ----------- |
| extend_keywords  | Array | No       | Keyword search list, used for searching products by keywords. Supports multiple keyword combination searches. Each object in the array contains the following fields:<br>• field - Search field, options: all (all), product_name (product name), product_link (product URL), advertiser_name (advertiser name)<br>• logic_operator - Logical operator, options: and, or<br>• value - Search content |
| exclude_keywords | Array | No       | Exclude keyword list, used for excluding products containing specific keywords. Same structure as extend_keywords |

### Request Example

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

## Response Parameters

### Response Structure

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

### Response Field Descriptions

| Field     | Type    | Description |
| --------- | ------- | ----------- |
| code      | Integer | Business status code, 200 indicates success |
| message   | String  | Response message, usually "success" when successful |
| data      | Object  | Response data object |
| version   | string  | API version |
| timestamp | number  | Response timestamp |
| sign      | string  | Response signature |
| remaining_credits | Long    | Current remaining available credits after this request |
| consumed_credits  | Long    | Credits consumed by this request                       |
| success   | boolean | Whether the request was successful |
| fail      | boolean | Whether the request failed |

### Pagination Information Fields

| Field        | Type    | Description |
| ------------ | ------- | ----------- |
| current_page | Integer | Current page number |
| data         | Array   | Data list, contains array of product information |
| last_page    | Integer | Last page number, can be used to determine total pages |
| per_page     | Integer | Page size, number of data items returned per page |
| total        | Integer | Total data count, total number of products meeting filter criteria |

### Product Information Fields

| Field               | Type         | Description |
| ------------------- | ------------ | ----------- |
| id                  | String       | Product ID, unique identifier for the product |
| name                | String       | Product name |
| price               | Double       | Product price (original currency) |
| price_usd           | Double       | Product USD price, converted to USD for easy comparison |
| currency            | String       | Currency unit, such as USD, EUR, etc. |
| image_url           | String       | Product main image URL, the primary display image for the product |
| images              | String Array | Product image link list, contains all product image URLs |
| source_product_id   | String       | E-commerce platform product ID, product identifier on the original e-commerce platform |
| source_product_link | String       | Product link, product detail page URL on the e-commerce platform |
| e_commerce_platform | String       | E-commerce platform, name of the e-commerce platform where the product is located |
| creation_time       | Long         | Product creation time, timestamp: seconds |
| user_collected      | Integer      | Whether collected, options:<br>• 1 - Not collected<br>• 2 - Collected |

### Product Advertising Data Fields

| Field              | Type    | Description |
| ------------------ | ------- | ----------- |
| ad_status          | Integer | Ad status, current ad placement status of the product |
| ad_forecast        | Integer | Product score, product stage score evaluated by AI |
| active_ad_count    | Integer | Active ad count, number of ads currently being placed |
| ad_count           | Integer | Ad count, total number of ads created for the product |
| active_adset_count | Integer | Active ad set count, number of ad sets currently being placed |
| adset_count        | Integer | Total ad set count, total number of ad sets created for the product |
| adset_count_24h    | Integer | 24-hour ad set count, number of ad sets added in the last 24 hours |
| active_days        | Integer | Ad days, number of days the product has been continuously advertising |
| ad_started_at      | Long    | Ad start time, timestamp: seconds. Time when the product first started advertising |
| ad_ended_at        | Long    | Ad end time, timestamp: seconds. End time of the last ad placement for the product |
| ad_cost            | Double  | Ad spend, unit: USD. Cumulative advertising investment cost for the product |
| ad_audience_reach  | Integer | Reach, total number of unique users reached by the ads |

### Store Information Fields (store)

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

| Field               | Type          | Description |
| ------------------- | ------------- | ----------- |
| id                  | String        | Store ID, unique identifier for the store |
| name                | String        | Store name |
| logo_url            | String        | Store logo, store logo image URL |
| country             | String        | Store country, country where the store is registered or primarily operates |
| source_store_link   | String        | Store link, store homepage URL on the e-commerce platform |
| e_commerce_platform | String        | E-commerce platform, name of the e-commerce platform where the store is located |
| e_commerce_types    | Integer Array | E-commerce types, business type identifiers of the store |
| ad_count            | Integer       | Store creative count, total number of ad creatives created by the store |
| adset_count         | Integer       | Total ad set count, total number of ad sets created by the store |
| monthly_sales       | Integer       | Monthly sales, monthly sales count for the store (estimated value) |

## Response Example

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

## Error Code Descriptions

| Error Code | Description |
| ---------- | ----------- |
| 200        | Success |
| 400        | Request parameter error, please check parameter format and value range |
| 401        | Unauthorized, API key is invalid or expired |
| 403        | Insufficient permissions, insufficient account balance or restricted API access |
| 404        | API path does not exist |
| 444        | Too many requests, rate limit triggered |
| 500        | Internal server error, please try again later |

## 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