# Advertisement Library Detail API

## API Information

- **API Name**: Get Advertisement Library Detail
- **Request Method**: POST
- **API URL**: `/open-api/v1/data`
- **Interface URI path**: `/v3/api/open/lib-ads/detail`
- **Description**: Get detailed advertisement information by advertisement ID, including advertisement history change data
- **Pricing**: Details API pricing rules: 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 Name | Type   | Description                     | Example                       | Required | Default |
| -------------- | ------ | ------------------------------- | ----------------------------- | -------- | ------- |
| key            | string | User's external API request key | "your_api_key_here"           | Yes      |         |
| uri            | string | Interface URI path              | "/v3/api/open/lib-ads/detail" | Yes      |         |
| params         | object | Interface parameter object      | See parameter list below      | Yes      |         |

#### Parameter List (params object)

| Parameter Name | Type   | Description                                   | Example                            | Required | Default |
| -------------- | ------ | --------------------------------------------- | ---------------------------------- | -------- | ------- |
| id             | string | Advertisement ID, unique identifier in system | "06c7df340f26f2539c8dada9fa5afe27" | Yes      |         |

#### 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/lib-ads/detail",
    "params": {
      "id": "06c7df340f26f2539c8dada9fa5afe27"
    }
  }'
```

### Response

#### Response Body Structure

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "ads_history": {
      // Advertisement history change data
    },
    "advertisement": {
      // Detailed advertisement information
    }
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 1,
  "success": true,
  "fail": false
}
```

#### Response Field Description

##### Main Response Fields

| Field Name        | Type    | Description                        |
| ----------------- | ------- | ---------------------------------- |
| **ads_history**   | object  | Advertisement history change data  |
| **advertisement** | object  | Detailed advertisement information |
| **version**       | string  | API version number                 |
| **timestamp**     | long    | Response timestamp                 |
| **sign**          | string  | Response signature                 |
| **remaining_credits** | number        | Current remaining available credits after this request |
| **consumed_credits**  | number        | Credits consumed by this request                       |
| **success**       | boolean | Whether the request was successful |
| **fail**          | boolean | Whether the request failed         |

##### Advertisement History Fields (ads_history)

| Field Name  | Type   | Description                     |
| ----------- | ------ | ------------------------------- |
| ad_cost     | object | Advertisement cost history data |
| adset_count | object | Adset count history data        |

##### History Data Timeline Fields (timeline)

| Field Name | Type   | Description              |
| ---------- | ------ | ------------------------ |
| count      | double | Value                    |
| date       | string | Date (YYYY-MM-DD format) |

##### Advertisement Detail Fields (advertisement)

| Field Name          | Type   | Description                                                   |
| ------------------- | ------ | ------------------------------------------------------------- |
| id                  | string | Advertisement ID, unique identifier in system                 |
| active_days         | long   | Advertisement duration                                        |
| ad_audience         | object | Advertisement audience information                            |
| ad_audience_reach   | long   | Advertisement reach                                           |
| ad_caption          | string | Advertisement description                                     |
| ad_content          | string | Advertisement content                                         |
| ad_cost             | double | Advertisement cost                                            |
| ad_forecast         | long   | Advertisement forecast status (1:Testing 2:Scaling 3:Winning) |
| ad_link             | string | Advertisement link                                            |
| ad_link_description | string | Advertisement link description                                |
| ad_platform         | array  | Advertisement platforms list                                  |
| ad_started_at       | long   | Advertisement creation time                                   |
| ad_status           | long   | Advertisement status (1:Active 2:Inactive 3:Removed)          |
| ad_title            | string | Advertisement title                                           |
| adset_count         | long   | Adset count                                                   |
| advertiser          | object | Advertiser information                                        |
| button_text         | string | Button text                                                   |
| button_type         | string | Button type                                                   |
| cards               | array  | Carousel list                                                 |
| country             | array  | Target countries list                                         |
| first_discovered_at | long   | First discovered time                                         |
| images              | array  | Advertisement images list                                     |
| landing_page_type   | long   | Landing page type                                             |
| landing_pages       | array  | Landing page URLs list                                        |
| language            | string | Advertisement language                                        |
| last_discovered_at  | long   | Last updated time                                             |
| latest_actived_at   | long   | Latest active time                                            |
| media_format        | long   | Media format type                                             |
| products            | array  | Advertisement products list                                   |
| source_ad_id        | string | Source ad ID                                                  |
| store               | object | Advertisement store information                               |
| user_collected      | long   | User collection status (1:Collected 2:Not collected)          |
| videos              | array  | Advertisement videos list                                     |
| size                | string | Size information                                              |
| clarity             | string | Clarity information                                           |
| aspect_ratio        | string | Aspect ratio information                                      |
| ai_analysis         | object | AI analysis results                                           |

##### AI Analysis Object Fields (ai_analysis)

| Field Name                  | Type   | Description                        |
| --------------------------- | ------ | ---------------------------------- |
| ai_analysis_human_presenter | string | Whether human presenter is present |
| ai_analysis_language        | string | Video language                     |
| ai_analysis_main_hook       | string | Main hook content                  |
| ai_analysis_script          | string | Video script                       |
| ai_analysis_tags            | array  | Video tags list                    |

##### Advertiser Information Object Fields (advertiser)

| Field Name             | Type   | Description                      |
| ---------------------- | ------ | -------------------------------- |
| id                     | string | Advertiser ID                    |
| name                   | string | Advertiser name                  |
| ad_count               | long   | Advertiser ad count              |
| ad_country             | array  | Advertiser target countries      |
| ads_library_link       | string | Ads library link                 |
| adset_count            | long   | Adset count                      |
| e_commerce_platform    | string | E-commerce platform              |
| like_count             | long   | Like count                       |
| profile_picture_url    | string | Profile picture URL              |
| source_advertiser_id   | string | Source advertiser ID             |
| source_advertiser_link | string | Source advertiser link           |
| user_blocked           | long   | User blocked status (1:Yes 2:No) |

##### Product Information Object Fields (products)

| Field Name          | Type   | Description         |
| ------------------- | ------ | ------------------- |
| id                  | string | Product ID          |
| name                | string | Product name        |
| ad_count            | long   | Product ad count    |
| category_id         | string | Category ID         |
| category_name       | string | Category name       |
| creation_time       | long   | Creation time       |
| currency            | string | Currency type       |
| image_url           | string | Product image URL   |
| price               | double | Product price       |
| price_usd           | double | Product USD price   |
| source_product_link | string | Source product link |

##### Store Information Object Fields (store)

| Field Name          | Type   | Description           |
| ------------------- | ------ | --------------------- |
| id                  | string | Store ID              |
| name                | string | Store name            |
| ad_count            | long   | Store ad count        |
| categories          | array  | Store categories list |
| e_commerce_platform | string | E-commerce platform   |
| e_commerce_types    | array  | E-commerce types list |
| logo_url            | string | Store logo URL        |
| source_store_link   | string | Source store link     |

##### Store Category Object Fields (categories)

| Field Name | Type   | Description           |
| ---------- | ------ | --------------------- |
| id         | string | Category ID           |
| name_en    | string | Category English name |
| name_zh    | string | Category Chinese name |

##### Video Information Object Fields (videos)

| Field Name | Type   | Description              |
| ---------- | ------ | ------------------------ |
| url        | string | Video URL                |
| cover_url  | string | Cover URL                |
| duration   | long   | Video duration (seconds) |
| width      | long   | Video width              |
| height     | long   | Video height             |

##### Image Information Object Fields (images)

| Field Name | Type   | Description  |
| ---------- | ------ | ------------ |
| url        | string | Image URL    |
| width      | long   | Image width  |
| height     | long   | Image height |

##### Carousel Information Object Fields (cards)

| Field Name | Type   | Description                  |
| ---------- | ------ | ---------------------------- |
| url        | string | Media URL                    |
| cover_url  | string | Cover URL                    |
| duration   | long   | Duration (for videos)        |
| width      | long   | Width                        |
| height     | long   | Height                       |
| media_type | long   | Media type (1:Video 2:Image) |

#### Response Example

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "ads_history": {
      "ad_cost": {
        "timeline": [
          {
            "count": 0.0,
            "date": "2025-06-04"
          },
          {
            "count": 0.0,
            "date": "2025-06-05"
          }
        ]
      },
      "adset_count": {
        "timeline": [
          {
            "count": 1.0,
            "date": "2025-06-04"
          },
          {
            "count": 1.0,
            "date": "2025-06-05"
          }
        ]
      }
    },
    "advertisement": {
      "id": "9a4566becbe35c6f6c0f1beac8dd6e30",
      "active_days": 1,
      "ad_caption": "ladyluxve.com",
      "ad_content": "🚨 ALERTA TENDENCIA 🚨\nEl botín que está arrasando en redes sociales ya llegó a Venezuela 🇻🇪",
      "ad_forecast": 1,
      "ad_link": "https://www.facebook.com/ads/library/?id=1124613119690978",
      "ad_link_description": "⭐⭐⭐⭐⭐",
      "ad_platform": [
        "FACEBOOK",
        "INSTAGRAM",
        "AUDIENCE_NETWORK",
        "MESSENGER",
        "THREADS"
      ],
      "ad_started_at": 1749020400,
      "ad_status": 3,
      "ad_title": "35% OFF Hoy+ Envio GRATIS",
      "adset_count": 1,
      "advertiser": {
        "id": "7302fd79a2d742bb6c0f1beac8dd6e30",
        "name": "Lady Lux",
        "ad_count": 11,
        "ad_country": ["other"],
        "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=685400174653320",
        "adset_count": 11,
        "e_commerce_platform": "shopify",
        "like_count": 1201,
        "profile_picture_url": "https://fb-cdn.pipispy.com/images/38f38e24fa774ca1bf01da9aba9ac47e.png",
        "source_advertiser_id": "685400174653320",
        "source_advertiser_link": "https://facebook.com/61576957564176",
        "user_blocked": 2
      },
      "button_text": "Shop now",
      "button_type": "SHOP_NOW",
      "cards": [],
      "country": ["other"],
      "first_discovered_at": 1749024028,
      "images": [],
      "landing_page_type": 1,
      "landing_pages": [
        "https://ladyluxve.com/products/botin%E2%84%A2-starway"
      ],
      "language": "es",
      "last_discovered_at": 1749108995,
      "latest_actived_at": 1749106800,
      "media_format": 1,
      "products": [
        {
          "currency": "USD",
          "id": "dd66f501d1faa6adbe16801b708c35d5",
          "name": "Botin™ - Starway",
          "price": 49.99,
          "ad_count": 3,
          "creation_time": 1748732926,
          "image_url": "https://fb-cdn.pipispy.com/images/pimg_85d72df090674a0b56a4f.png",
          "price_usd": 49.99,
          "source_product_link": "https://ladyluxve.com/products/botin%E2%84%A2-starway"
        }
      ],
      "source_ad_id": "1124613119690978",
      "store": {
        "categories": [
          {
            "id": "62739ba938365b2f72048eca",
            "name_en": "Shoes",
            "name_zh": "鞋类"
          }
        ],
        "id": "389f77b24aefc6ffbe16801b708c35d5",
        "name": "Lady lux",
        "ad_count": 11,
        "e_commerce_platform": "shopify",
        "logo_url": "http://ladyluxve.com/cdn/shop/files/ladyancho.jpg?crop=center&height=32&v=1748537443&width=32",
        "source_store_link": "https://ladyluxve.com"
      },
      "user_collected": 2,
      "videos": [
        {
          "duration": 16,
          "height": 1280,
          "url": "https://fb-cdn.pipispy.com/videos/a98e21abd3b3b2340f9998d5a8f209ac.mp4",
          "width": 720,
          "cover_url": "https://fb-cdn.pipispy.com/images/40960e1f77f4077634bf463593b629ba.png"
        }
      ],
      "size": "9:16",
      "clarity": "FHD",
      "aspect_ratio": "720x1280"
    }
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 1,
  "success": true,
  "fail": false
}
```

### Error Codes

| Error Code | Description                      |
| ---------- | -------------------------------- |
| 400        | Bad Request - Invalid parameters |
| 401        | Unauthorized - Invalid API key   |
| 500        | Internal Server Error            |

## Notes

1. Advertisement ID must be a valid system internal ID
2. URLs in response have been converted to CDN addresses
3. All timestamps are Unix timestamps (seconds)
4. AI analysis fields are only returned for video advertisements
5. Some fields may be empty depending on advertisement type and data completeness