# Ad Library Product Details API

## API Information

- **API Name**: Ad Library Product Details
- **Request Method**: POST
- **API Endpoint**: `/open-api/v1/data`
- **API Path**: `/v3/api/open/ppspy/ad-products/detail`
- **API Description**: Retrieve detailed information about ad library products by product ID, including basic product information, advertising data, store information, advertiser information, and ad count trends
- **Pricing**: Base fee: 1 credit/request. Free access conditions (if either is met): Details for this ID have been retrieved within the past 3 days; This ID appeared in your leaderboard list query results within the past 3 days.

**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/detail" | Yes      |         |
| params    | object | API input parameters object | See parameter list                | Yes      |         |

### Path Parameters

| Parameter | Type   | Required | Description |
| --------- | ------ | -------- | ----------- |
| id        | String | Yes      | Product ID, used to identify the specific product to query. Can be obtained from the product search API response |

### 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/detail",
    "params": {
      "id": "5b9ac27f7b3d21aecdca5cb00be71baa"
    }
  }'
```

## Response Parameters

### Response Structure

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "product": {},
    "store": {},
    "advertisers": [],
    "ad_started_history": []
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 1,
  "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 |

### Data Object Fields (data)

| Field              | Type  | Description |
| ------------------ | ----- | ----------- |
| product            | Object | Product information, contains complete detailed product data |
| store              | Object | Store information, detailed information about the store to which the product belongs |
| advertisers        | Array  | Advertiser information list, data for all advertisers promoting this product |
| ad_started_history | Array  | Ad count trends, historical trend data of product ad placements |

### Product Information Fields (product)

#### Basic Information

| 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 price in USD, 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 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 |
| store_id             | String       | Store ID, unique identifier of the store to which the product belongs |
| category_id          | String       | Category ID, unique identifier of the category to which the product belongs |
| category_name        | String       | Category name, name of the category to which the product belongs |
| creation_time        | Long         | Product creation time, timestamp: seconds |
| user_collected       | Integer      | Whether collected, possible values:<br>• 1 - Not collected<br>• 2 - Collected |

#### Advertising Data

| Field              | Type         | Description |
| ------------------ | ------------ | ----------- |
| ad_status          | Integer      | Ad status, possible values: 1-Active, 2-Stopped |
| ad_forecast        | Integer      | AI score, possible values: 1-Testing phase, 2-Growth phase, 3-Profit phase |
| 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 |
| ad_platform        | String Array | Ad platform list, platforms where the product ads are placed, such as FACEBOOK, INSTAGRAM, etc. |

### Store Information Fields (store)

| Field                     | Type    | Description |
| ------------------------- | ------- | ----------- |
| id                        | String  | Store ID, unique identifier for the store |
| name                      | String  | Store name |
| logo_url                  | String  | Store logo image URL |
| e_commerce_platform       | String  | E-commerce platform, name of the e-commerce platform where the store is located |
| source_store_link         | String  | Store link, store homepage URL on the e-commerce platform |
| month_visits              | Integer | Monthly visits, monthly visit count for the store (estimated value) |
| published_products_count  | Integer | Product count, total number of products published by the store |
| monthly_sales             | Integer | Monthly sales, monthly sales count for the store (estimated value) |

### Advertiser Information Fields (advertisers)

advertisers is an array containing information about all advertisers promoting this product. Each advertiser object contains the following fields:

#### Basic Information

| Field                   | Type   | Description |
| ----------------------- | ------ | ----------- |
| id                      | String | Advertiser ID, unique identifier for the advertiser |
| name                    | String | Advertiser name |
| profile_picture_url     | String | Advertiser profile picture link |
| source_advertiser_id    | String | Advertiser page ID, page identifier on the ad platform |
| source_advertiser_link  | String | Advertiser page link, advertiser page URL on the ad platform |
| ads_library_link        | String | Advertiser ad library link, link to view all ads from this advertiser |
| category_name           | String | Category, category to which the advertiser belongs |
| creation_time           | Long   | Creation time, timestamp: seconds |

#### Advertising Data

| Field              | Type         | Description |
| ------------------ | ------------ | ----------- |
| ad_status          | Integer      | Ad status, possible values: 1-Active, 2-Stopped |
| active_ad_count    | Integer      | Active ad count, number of ads currently being placed by this advertiser |
| inactive_ad_count  | Integer      | Inactive ad count, number of ads that have been paused |
| removed_ad_count   | Integer      | Removed ad count, number of ads that have been deleted or removed |
| ad_count           | Integer      | Ad creative count, total number of ads created by this advertiser |
| adset_count        | Integer      | Ad set count, total number of ad sets created by this advertiser |
| active_days        | Integer      | Ad days, number of days this advertiser has been continuously advertising |
| ad_started_at      | Long         | Ad start time, timestamp: seconds |
| ad_ended_at        | Long         | Ad end time, timestamp: seconds |
| ad_country         | String Array | Country list, country codes where this advertiser's ads are placed |
| ad_platform        | String Array | Ad platform list, ad platforms used by this advertiser |
| like_count         | Integer      | Like count, total likes received by this advertiser's ads |
| ad_source          | Integer      | Ad source |

### Ad Trend Data Fields (ad_started_history)

ad_started_history is an array recording the change in product ad count over time. Each trend data point contains the following fields:

| Field | Type    | Description |
| ----- | ------- | ----------- |
| date  | String  | Date, UTC time. Format: YYYY-MM-DD |
| count | Integer | Ad count, number of ads corresponding to this date |

## Response Example

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "advertisers": [
      {
        "id": "f57f4c9d3ea20be66a132adb5f557eba",
        "name": "wijnvoordeel.be",
        "active_ad_count": 9,
        "active_days": 780,
        "ad_count": 321,
        "ad_country": [
          "BE",
          "other"
        ],
        "ad_ended_at": 1766995200,
        "ad_started_at": 1699603200,
        "ad_status": 1,
        "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=186022184808923",
        "adset_count": 531,
        "creation_time": 1318448479,
        "inactive_ad_count": 0,
        "like_count": 19420,
        "profile_picture_url": "https://scontent-lga3-1.xx.fbcdn.net/v/t39.35426-6/599566144_1210304384349710_4804416712767355916_n.jpg?stp=dst-jpg_s60x60_tt6&_nc_cat=111&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=UydCX9qVwIMQ7kNvwGqJ0kM&_nc_oc=AdnRT5BJoxS5kk-6exgTkCsIjeAeP4S6lmunXkvWZZOS6QNPr_cXeohqsKL1RegXxU4&_nc_zt=14&_nc_ht=scontent-lga3-1.xx&_nc_gid=lEhGO0OMT5L5L9xSpwx3OA&oh=00_AfnI22FlLJw3cHbRiXqUAIQRp1pSWWmgsYlAgNt9RC5y3Q&oe=69592A57",
        "removed_ad_count": 312,
        "ad_source": 1,
        "category_name": "Wine, Beer & Spirits Store",
        "source_advertiser_id": "186022184808923",
        "source_advertiser_link": "https://facebook.com/WijnvoordeelBE"
      }
    ],
    "product": {
      "currency": "EUR",
      "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"
      ],
      "name": "Infinitum Grillo",
      "price": 5.79,
      "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,
      "category_id": "62739aec38365b2f72048ebd",
      "ad_platform": [
        "FACEBOOK",
        "INSTAGRAM",
        "MESSENGER",
        "THREADS"
      ],
      "category_name": "Food",
      "e_commerce_platform": "magento",
      "price_usd": 6.82,
      "source_product_id": "c068345331a01d1216591db170f03672",
      "image_url": "https://fb-cdn.ppspy.com/images/pimg_c1cb26db9e59ba4c70688.png",
      "source_product_link": "https://www.wijnvoordeel.be/infinitum-grillo?channable=019969736b75004b3230303738324e",
      "store_id": "2382cd09c06c7d31cdca5cb00be71baa",
      "user_collected": 2
    },
    "store": {
      "id": "2382cd09c06c7d31cdca5cb00be71baa",
      "name": "wijnvoordeel.be",
      "e_commerce_platform": "magento",
      "logo_url": "https://fb-cdn.pipiads.com/icon_ad0a30d8c8334ccbf37488a8ce91377b.png",
      "month_visits": 19928,
      "source_store_link": "http://wijnvoordeel.be"
    },
    "ad_started_history": [
      {
        "count": 1,
        "date": "2025-12-27"
      }
    ]
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 1,
  "success": true,
  "fail": false
}
```

## Error Code Descriptions

| Error Code | Description |
| ---------- | ----------- |
| 200        | Success |
| 400        | Request parameter error, incorrect product ID format |
| 401        | Unauthorized, API key is invalid or expired |
| 403        | Insufficient permissions, insufficient account balance or restricted API access |
| 404        | Product does not exist, product with specified ID not found |
| 444        | Too many requests, rate limit triggered |
| 500        | Internal server error, please try again later |

## Notes

1. **Product ID Acquisition**: Product ID must be obtained from the ad product search API (`/v3/api/open/ppspy/ad-products/search`) response
2. **Data Integrity**: Some fields may be null, indicating that the data has not been collected or is not applicable to the product
3. **Advertiser Count**: The `advertisers` array may contain multiple advertisers, indicating that multiple advertisers are promoting the same product
4. **Trend Data**: `ad_started_history` provides time series data that can be used to draw trend charts
5. **Time Format**:
   - Product and advertiser time fields use Unix timestamps (seconds)
   - Trend data dates use UTC time in YYYY-MM-DD format
6. **Currency Units**: All price-related fields (`price`, `price_usd`, `ad_cost`) may have different units, pay attention to distinguish them
7. **Ad Platforms**: The `ad_platform` field may contain multiple platforms, such as FACEBOOK, INSTAGRAM, AUDIENCE_NETWORK, MESSENGER, etc.
8. **Category Information**: Products and advertisers may belong to different categories, `category_id` and `category_name` correspond to product and advertiser categories respectively
9. **Data Updates**: Ad data is updated regularly, it is recommended to re-query periodically to get the latest data
10. **Collection Status**: The `user_collected` field reflects the collection status of the current API user, different users may get different values when querying the same product