# Advertiser Details API

## API Information

- **API Name**: Get Advertiser Details
- **Request Method**: POST
- **API Endpoint**: `/open-api/v1/data`
- **API Path**: `/v3/api/open/top-advertiser/detail`
- **API Description**: Retrieve detailed advertiser information by advertiser ID
- **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 | Type   | Description                 | Example                           | Required | Default |
| --------- | ------ | --------------------------- | --------------------------------- | -------- | ------- |
| key       | string | External API request key    | "your_api_key_here"               | Yes      |         |
| uri       | string | API path                    | "/v3/api/open/top-advertiser/detail" | Yes      |         |
| params    | object | API input parameters object | See parameter list                | Yes      |         |

### Parameter List (params object)

| Parameter | Type   | Required | Description |
| --------- | ------ | -------- | ----------- |
| id        | String | Yes      | Advertiser ID (e.g., `60bf09612980dde5e9564279`), corresponds to the `id` field in the advertiser leaderboard list 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/top-advertiser/detail",
    "params": {
      "id": "60bf09612980dde5e9564279"
    }
  }'
```

## Response Parameters

### Response Structure

```json
{
  "code": 200,
  "message": "success",
  "data": {},
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 1,
  "success": true,
  "fail": false
}
```

### Response Field Descriptions

| Field     | Type        | Description |
| --------- | ----------- | ----------- |
| code      | Integer     | Response status code, 200 indicates success |
| message   | String      | Response message |
| data      | Object      | Advertiser detail information |
| version   | String      | API version |
| timestamp | Number/null | Response timestamp (null when unavailable) |
| sign      | String/null | Response signature (null when unavailable) |
| 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 |

### Advertiser Details Fields

#### Basic Information

| Field            | Type    | Description |
| ---------------- | ------- | ----------- |
| id               | String  | Advertiser ID |
| root_path        | String  | Advertiser domain |
| app_image        | String  | Advertiser icon URL |
| ad_platform_list | Array   | Ad platform list (tiktok, facebook, facebook-library) |
| shop_type        | Array   | E-commerce system type list (shopify, woocommerce, etc.) |
| data_count       | Number  | Total ad data count |
| monthly_visits   | Number  | Website monthly visits |
| first_data_time  | Number  | First data time (timestamp, seconds) |
| found_time       | Number  | First discovery time (timestamp, seconds) |
| latest_found_time| Number  | Latest discovery time (timestamp, seconds) |
| region           | Array   | Placement region list (country codes) |
| is_collection    | Boolean | Whether the current user has collected this advertiser |
| is_ai            | Boolean | Whether AI-related advertiser |
| is_drama         | Boolean | Whether short drama-related advertiser |
| all_shop_type    | Array   | All associated e-commerce system types |

#### All-Platform Summary Data

| Field                 | Type    | Description |
| --------------------- | ------- | ----------- |
| all_data_count        | Long    | Total ad count across all platforms |
| all_play_count        | Long    | Total ad play count across all platforms |
| all_page_count        | Long    | Total advertiser account count across all platforms |
| all_put_days          | Long    | Placement days across all platforms |
| all_found_time        | Long    | Earliest discovery time across all platforms (timestamp, seconds) |
| all_latest_found_time | Long    | Latest discovery time across all platforms (timestamp, seconds) |
| all_min_cpm           | Double  | Minimum CPM across all platforms (USD) |
| all_max_cpm           | Double  | Maximum CPM across all platforms (USD) |
| all_min_cpa           | Long    | Minimum estimated order count across all platforms |
| all_max_cpa           | Long    | Maximum estimated order count across all platforms |
| all_store_ad_state    | Integer | Overall ad status (-1=stopped, 1=active) |

#### TikTok Platform Data

| Field                       | Type    | Description |
| --------------------------- | ------- | ----------- |
| tiktok_data_count           | Long    | Total ad count on TikTok platform |
| tiktok_play_count           | Long    | Total ad play count on TikTok platform |
| tiktok_page_count           | Long    | Advertiser account count on TikTok platform |
| tiktok_popular_person_count | Long    | Popular creator count on TikTok platform |
| tiktok_put_days             | Long    | Placement days on TikTok platform |
| tiktok_found_time           | Long    | First discovery time on TikTok platform (timestamp, seconds) |
| tiktok_latest_found_time    | Long    | Latest discovery time on TikTok platform (timestamp, seconds) |
| tiktok_min_cpm              | Double  | Minimum CPM on TikTok platform (USD) |
| tiktok_max_cpm              | Double  | Maximum CPM on TikTok platform (USD) |
| tiktok_min_cpa              | Long    | Minimum estimated order count on TikTok platform |
| tiktok_max_cpa              | Long    | Maximum estimated order count on TikTok platform |
| tiktok_store_ad_state       | Integer | TikTok ad status (-1=stopped, 1=active) |

#### Facebook Platform Data

| Field                      | Type    | Description |
| -------------------------- | ------- | ----------- |
| facebook_data_count        | Long    | Total ad count on Facebook platform |
| facebook_play_count        | Long    | Total ad play count on Facebook platform |
| facebook_page_count        | Long    | Advertiser account count on Facebook platform |
| facebook_put_days          | Long    | Placement days on Facebook platform |
| facebook_found_time        | Long    | First discovery time on Facebook platform (timestamp, seconds) |
| facebook_latest_found_time | Long    | Latest discovery time on Facebook platform (timestamp, seconds) |
| facebook_min_cpm           | Double  | Minimum CPM on Facebook platform (USD) |
| facebook_max_cpm           | Double  | Maximum CPM on Facebook platform (USD) |
| facebook_min_cpa           | Long    | Minimum estimated order count on Facebook platform |
| facebook_max_cpa           | Long    | Maximum estimated order count on Facebook platform |
| facebook_store_ad_state    | Integer | Facebook ad status (-1=stopped, 1=active) |

#### Meta Ad Library Data

| Field                                   | Type    | Description |
| --------------------------------------- | ------- | ----------- |
| facebook_library_data_count             | Long    | Total ad count in Meta Ad Library |
| facebook_library_play_count             | Long    | Total ad play count in Meta Ad Library |
| facebook_library_page_count             | Long    | Advertiser account count in Meta Ad Library |
| facebook_library_put_days               | Long    | Placement days in Meta Ad Library |
| facebook_library_found_time             | Long    | First discovery time in Meta Ad Library (timestamp, seconds) |
| facebook_library_latest_found_time      | Long    | Latest discovery time in Meta Ad Library (timestamp, seconds) |
| facebook_library_min_cpm                | Double  | Minimum CPM in Meta Ad Library (USD) |
| facebook_library_max_cpm                | Double  | Maximum CPM in Meta Ad Library (USD) |
| facebook_library_min_cpa                | Long    | Minimum estimated order count in Meta Ad Library |
| facebook_library_max_cpa                | Long    | Maximum estimated order count in Meta Ad Library |
| facebook_library_reach                  | Long    | Reach in Meta Ad Library |
| facebook_library_adset_count            | Long    | Total ad set count in Meta Ad Library |
| facebook_library_adset_active_count     | Long    | Active ad set count currently being placed in Meta Ad Library |
| facebook_library_ad_active_count        | Long    | Active ad count currently being placed in Meta Ad Library |
| facebook_library_ad_inactive_count      | Long    | Paused ad count in Meta Ad Library |
| facebook_library_ad_offline_count       | Long    | Offline ad count in Meta Ad Library |
| facebook_library_ad_state               | Integer | Meta Ad Library ad status (-1=stopped, 1=active) |

#### Website Information (website_info)

| Field                 | Type   | Description |
| --------------------- | ------ | ----------- |
| website_id            | String | Website unique identifier |
| website_icon          | String | Website icon URL |
| website_title         | String | Website title |
| website_url           | String | Website link |
| website_languages     | Array  | Languages used by the website |
| website_countries     | Array  | Countries where the website is located |
| website_currencies    | Array  | Currencies supported by the website |
| website_monthly_visits| Long   | Website monthly visits |
| website_bounce_rate   | Double | Website bounce rate (0.0-1.0) |
| website_visit_seconds | Long   | Website average visit duration (seconds) |

## Response Example

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": "61f57e4d9a301ef93d53b88a",
    "root_path": "example-shop.com",
    "app_image": "https://fb-cdn.pipispy.com/images/example.png",
    "ad_platform_list": ["tiktok", "facebook", "facebook-library"],
    "shop_type": ["shopify"],
    "data_count": 1250,
    "monthly_visits": 5000000,
    "first_data_time": 1675830644,
    "found_time": 1675830644,
    "latest_found_time": 1752202412,
    "region": ["US", "CA", "GB", "DE", "FR"],
    "is_collection": false,
    "is_ai": false,
    "is_drama": false,
    "all_shop_type": ["shopify"],
    "all_data_count": 2500,
    "all_play_count": 76792774635,
    "all_page_count": 3256,
    "all_put_days": 180,
    "all_found_time": 1675830644,
    "all_latest_found_time": 1752202412,
    "all_min_cpm": 15.5,
    "all_max_cpm": 45.8,
    "all_min_cpa": 50,
    "all_max_cpa": 500,
    "all_store_ad_state": 1,
    "tiktok_data_count": 1000,
    "tiktok_play_count": 50000000000,
    "tiktok_page_count": 1500,
    "tiktok_popular_person_count": 1157348,
    "tiktok_put_days": 150,
    "tiktok_found_time": 1675830644,
    "tiktok_latest_found_time": 1752202412,
    "tiktok_min_cpm": 18.0,
    "tiktok_max_cpm": 42.5,
    "tiktok_min_cpa": 60,
    "tiktok_max_cpa": 450,
    "tiktok_store_ad_state": 1,
    "facebook_data_count": 800,
    "facebook_play_count": 20000000000,
    "facebook_page_count": 1200,
    "facebook_put_days": 120,
    "facebook_found_time": 1680000000,
    "facebook_latest_found_time": 1752000000,
    "facebook_min_cpm": 12.0,
    "facebook_max_cpm": 38.0,
    "facebook_min_cpa": 45,
    "facebook_max_cpa": 400,
    "facebook_store_ad_state": 1,
    "facebook_library_data_count": 700,
    "facebook_library_play_count": 6792774635,
    "facebook_library_page_count": 556,
    "facebook_library_put_days": 90,
    "facebook_library_found_time": 1685000000,
    "facebook_library_latest_found_time": 1752202412,
    "facebook_library_min_cpm": 20.0,
    "facebook_library_max_cpm": 50.0,
    "facebook_library_min_cpa": 70,
    "facebook_library_max_cpa": 550,
    "facebook_library_reach": 15000000,
    "facebook_library_adset_count": 150,
    "facebook_library_adset_active_count": 80,
    "facebook_library_ad_active_count": 200,
    "facebook_library_ad_inactive_count": 100,
    "facebook_library_ad_offline_count": 400,
    "facebook_library_ad_state": 1,
    "website_info": {
      "website_id": "web_001",
      "website_icon": "https://fb-cdn.pipispy.com/images/icon.png",
      "website_title": "Example Shop",
      "website_url": "https://example-shop.com",
      "website_languages": ["en", "de", "fr"],
      "website_countries": ["US", "CA", "GB"],
      "website_currencies": ["USD", "EUR", "GBP"],
      "website_monthly_visits": 5000000,
      "website_bounce_rate": 0.45,
      "website_visit_seconds": 180
    }
  },
  "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, such as missing advertiser ID |
| 403        | Insufficient permissions |
| 404        | Advertiser does not exist |
| 444        | Too many requests, rate limit triggered |
| 500        | Internal server error |