# Ad Store Data Analysis API Endpoint

## 1. All Platform Data Statistical Analysis

### API Endpoint Information

- **API Endpoint Name**: Store Detail All Platform Data Statistical Analysis
- **Request Method**: POST
- **API Endpoint Address**: `/open-api/v1/data`
- **API Endpoint Path**: `/v3/api/open/store/allPlatform/dataAnalysis`
- **API Endpoint Description**: Get aggregated data analysis for a store across all platforms (TikTok, Facebook, Meta Ad Library)
- **Pricing**: `Free`

**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 | API Endpoint path                  | "/v3/api/open/store/allPlatform/dataAnalysis"     | Yes      |         |
| params         | object | API Endpoint input parameter object| See parameter list                                | Yes      |         |

#### Standard Response Fields

| Field Name | Type | Description |
| ---------- | ---- | ----------- |
| remaining_credits | Long | Current remaining available credits after this request |
| consumed_credits | Long | Credits consumed by this request |

#### Parameter List (params object)

| Parameter Name | Type   | Required | Description |
| -------------- | ------ | -------- | ----------- |
| id             | String | Yes      | Store ID is a 13-character string (e.g., `c2d5b2547218a`), corresponding to the `store_id` field in the store ranking list API endpoint response |
| start_time     | Long   | No       | Start time, timestamp, unit: seconds |
| end_time       | Long   | No       | End time, timestamp, unit: seconds |

#### 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/store/allPlatform/dataAnalysis",
    "params": {
      "id": "store_123456",
      "start_time": 1675830644,
      "end_time": 1752202412
    }
  }'
```

### Response Parameters

#### Response Body Structure

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

#### Data Field Descriptions

##### All Platform Aggregated Data

| Field Name         | Type       | Description |
| ------------------ | ---------- | ----------- |
| all_play_count     | Long       | All platform aggregated ad video play count (TikTok + Facebook + Meta Ad Library) |
| all_digg_count     | Long       | TikTok + Facebook like count (does not include Meta Ad Library) |
| all_digg_play_rate | BigDecimal | Like rate, i.e., (TikTok + Facebook likes) / (TikTok + Facebook plays), not multiplied by 100% |
| all_data_count     | Long       | All platform aggregated ad total count |
| all_min_cpm        | BigDecimal | All platform minimum ad spend (USD), i.e., sum of min_cpm for each platform |
| all_max_cpm        | BigDecimal | All platform maximum ad spend (USD), i.e., sum of max_cpm for each platform |
| all_put_days       | Long       | All platform delivery days, i.e., sum of delivery days for each platform (not affected by time range selector) |
| all_start_time     | Long       | All platform first ad time, takes the earliest time across all platforms (timestamp, seconds) |
| all_end_time       | Long       | All platform last ad time, takes the latest time across all platforms (timestamp, seconds) |

##### Daily Like Increment Analysis (digg_inc_analytic)

| Field Name           | Type | Description |
| -------------------- | ---- | ----------- |
| statistics_time      | Long | Statistics time (timestamp, seconds) |
| tiktokDiggIncCount   | Long | TikTok like increment for that day |
| facebookDiggIncCount | Long | Facebook like increment for that day |

##### Daily Ad Increment Analysis (adIncAnalytics)

| Field Name                  | Type | Description |
| --------------------------- | ---- | ----------- |
| statistics_time             | Long | Statistics time (timestamp, seconds) |
| tiktok_inc_data_count       | Long | TikTok ad count increment for that day |
| facebook_inc_data_count     | Long | Facebook ad count increment for that day |
| facebookLibraryIncDataCount | Long | Meta Ad Library ad count increment for that day |

##### Platform Data Analysis (tiktokAnalytic / facebookAnalytic / facebookLibraryAnalytic)

| Field Name     | Type       | Description |
| -------------- | ---------- | ----------- |
| play_count     | Long       | Platform ad video play count |
| digg_count     | Long       | Platform like count (Meta Ad Library does not have this field) |
| digg_play_rate | BigDecimal | Platform like rate, i.e., digg_count / play_count (Meta Ad Library does not have this field) |
| data_count     | Long       | Platform ad count |
| put_day        | Long       | Platform ad delivery days |
| min_cpm        | BigDecimal | Platform minimum ad spend (USD) |
| max_cpm        | BigDecimal | Platform maximum ad spend (USD) |
| start_time     | Long       | Platform first ad time (timestamp, seconds) |
| end_time       | Long       | Platform last ad time (timestamp, seconds) |

#### Response Example

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "all_play_count": 76792774635,
    "all_digg_count": 1500000000,
    "all_digg_play_rate": 0.0215,
    "all_data_count": 2500,
    "all_min_cpm": 45.5,
    "all_max_cpm": 130.3,
    "all_put_days": 360,
    "all_start_time": 1675830644,
    "all_end_time": 1752202412,
    "digg_inc_analytic": [
      {
        "statistics_time": 1752115200,
        "tiktokDiggIncCount": 1200000,
        "facebookDiggIncCount": 800000
      }
    ],
    "adIncAnalytics": [
      {
        "statistics_time": 1752115200,
        "tiktok_inc_data_count": 50,
        "facebook_inc_data_count": 30,
        "facebookLibraryIncDataCount": 20
      }
    ],
    "tiktokAnalytic": {
      "play_count": 50000000000,
      "digg_count": 1000000000,
      "digg_play_rate": 0.02,
      "data_count": 1000,
      "put_day": 150,
      "min_cpm": 18.0,
      "max_cpm": 42.5,
      "start_time": 1675830644,
      "end_time": 1752202412
    },
    "facebookAnalytic": {
      "play_count": 20000000000,
      "digg_count": 500000000,
      "digg_play_rate": 0.025,
      "data_count": 800,
      "put_day": 120,
      "min_cpm": 12.0,
      "max_cpm": 38.0,
      "start_time": 1680000000,
      "end_time": 1752000000
    },
    "facebookLibraryAnalytic": {
      "play_count": 6792774635,
      "digg_count": null,
      "digg_play_rate": null,
      "data_count": 700,
      "put_day": 90,
      "min_cpm": 15.5,
      "max_cpm": 49.8,
      "start_time": 1685000000,
      "end_time": 1752202412
    }
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 0,
  "success": true,
  "fail": false
}
```

---

## 2. TikTok Platform Data Statistical Analysis

### API Endpoint Information

- **API Endpoint Name**: TikTok Platform Data Statistical Analysis
- **Request Method**: POST
- **API Endpoint Address**: `/open-api/v1/data`
- **API Endpoint Path**: `/v3/api/open/store/tiktokPlatform/dataAnalysis`
- **API Endpoint Description**: Get ad data analysis for a store on the TikTok platform
- **Pricing**: `Free`

**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 | API Endpoint path                  | "/v3/api/open/store/tiktokPlatform/dataAnalysis"  | Yes      |         |
| params         | object | API Endpoint input parameter object| See parameter list                                | Yes      |         |

#### Parameter List (params object)

| Parameter Name | Type   | Required | Description |
| -------------- | ------ | -------- | ----------- |
| id             | String | Yes      | Store ID is a 13-character string (e.g., `c2d5b2547218a`), corresponding to the `store_id` field in the store ranking list API endpoint response |
| start_time     | Long   | No       | Start time, timestamp, unit: seconds |
| end_time       | Long   | No       | End time, timestamp, unit: seconds |

#### 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/store/tiktokPlatform/dataAnalysis",
    "params": {
      "id": "store_123456",
      "start_time": 1675830644,
      "end_time": 1752202412
    }
  }'
```

### Response Parameters

#### Response Body Structure

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

#### Data Field Descriptions

| Field Name     | Type       | Description |
| -------------- | ---------- | ----------- |
| play_count     | Long       | TikTok platform ad video play count |
| digg_count     | Long       | TikTok platform like count |
| digg_play_rate | BigDecimal | TikTok platform like rate |
| data_count     | Long       | TikTok platform ad count |
| put_day        | Long       | TikTok platform ad delivery days |
| min_cpm        | BigDecimal | TikTok platform minimum ad spend (USD) |
| max_cpm        | BigDecimal | TikTok platform maximum ad spend (USD) |
| min_cpa        | BigDecimal | TikTok platform minimum conversion count |
| max_cpa        | BigDecimal | TikTok platform maximum conversion count |
| start_time     | Long       | TikTok platform first ad time (timestamp, seconds) |
| end_time       | Long       | TikTok platform last ad time (timestamp, seconds) |

#### Response Example

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "play_count": 50000000000,
    "digg_count": 1000000000,
    "digg_play_rate": 0.02,
    "data_count": 1000,
    "put_day": 150,
    "min_cpm": 18.0,
    "max_cpm": 42.5,
    "min_cpa": 60.0,
    "max_cpa": 450.0,
    "start_time": 1675830644,
    "end_time": 1752202412
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 0,
  "success": true,
  "fail": false
}
```

---

## 3. Facebook Platform Data Statistical Analysis

### API Endpoint Information

- **API Endpoint Name**: Facebook Platform Data Statistical Analysis
- **Request Method**: POST
- **API Endpoint Address**: `/open-api/v1/data`
- **API Endpoint Path**: `/v3/api/open/store/facebookPlatform/dataAnalysis`
- **API Endpoint Description**: Get ad data analysis for a store on the Facebook platform
- **Pricing**: `Free`
**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 | API Endpoint path                  | "/v3/api/open/store/facebookPlatform/dataAnalysis" | Yes      |         |
| params         | object | API Endpoint input parameter object| See parameter list                                 | Yes      |         |

#### Parameter List (params object)

| Parameter Name | Type   | Required | Description |
| -------------- | ------ | -------- | ----------- |
| id             | String | Yes      | Store ID is a 13-character string (e.g., `c2d5b2547218a`), corresponding to the `store_id` field in the store ranking list API endpoint response |
| start_time     | Long   | No       | Start time, timestamp, unit: seconds |
| end_time       | Long   | No       | End time, timestamp, unit: seconds |

#### 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/store/facebookPlatform/dataAnalysis",
    "params": {
      "id": "store_123456",
      "start_time": 1675830644,
      "end_time": 1752202412
    }
  }'
```

### Response Parameters

#### Response Body Structure

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

#### Data Field Descriptions

| Field Name     | Type       | Description |
| -------------- | ---------- | ----------- |
| play_count     | Long       | Facebook platform ad video play count |
| digg_count     | Long       | Facebook platform like count |
| digg_play_rate | BigDecimal | Facebook platform like rate |
| data_count     | Long       | Facebook platform ad count |
| put_day        | Long       | Facebook platform ad delivery days |
| min_cpm        | BigDecimal | Facebook platform minimum ad spend (USD) |
| max_cpm        | BigDecimal | Facebook platform maximum ad spend (USD) |
| min_cpa        | BigDecimal | Facebook platform minimum conversion count |
| max_cpa        | BigDecimal | Facebook platform maximum conversion count |
| start_time     | Long       | Facebook platform first ad time (timestamp, seconds) |
| end_time       | Long       | Facebook platform last ad time (timestamp, seconds) |

#### Response Example

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "play_count": 20000000000,
    "digg_count": 500000000,
    "digg_play_rate": 0.025,
    "data_count": 800,
    "put_day": 120,
    "min_cpm": 12.0,
    "max_cpm": 38.0,
    "min_cpa": 45.0,
    "max_cpa": 400.0,
    "start_time": 1680000000,
    "end_time": 1752000000
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 0,
  "success": true,
  "fail": false
}
```

---

## 4. Meta Ad Library Data Statistical Analysis

### API Endpoint Information

- **API Endpoint Name**: Meta Ad Library Data Statistical Analysis
- **Request Method**: POST
- **API Endpoint Address**: `/open-api/v1/data`
- **API Endpoint Path**: `/v3/api/open/store/facebookLibraryPlatform/dataAnalysis`
- **API Endpoint Description**: Get data analysis for a store in the Meta Ad Library
- **Pricing**: `Free`
-
**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 | API Endpoint path                  | "/v3/api/open/store/facebookLibraryPlatform/dataAnalysis" | Yes      |         |
| params         | object | API Endpoint input parameter object| See parameter list                                        | Yes      |         |

#### Parameter List (params object)

| Parameter Name | Type   | Required | Description |
| -------------- | ------ | -------- | ----------- |
| id             | String | Yes      | Store unique identifier ID |
| start_time     | Long   | No       | Start time, timestamp, unit: seconds |
| end_time       | Long   | No       | End time, timestamp, unit: seconds |

#### 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/store/facebookLibraryPlatform/dataAnalysis",
    "params": {
      "id": "store_123456",
      "start_time": 1675830644,
      "end_time": 1752202412
    }
  }'
```

### Response Parameters

#### Response Body Structure

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

#### Data Field Descriptions

| Field Name     | Type       | Description |
| -------------- | ---------- | ----------- |
| data_count     | Long       | Meta Ad Library ad count |
| adset_count    | Long       | Meta Ad Library ad set count |
| audience_reach | Long       | Audience reach (EU & UK data only) |
| play_count     | Long       | Ad play count (EU & UK data only) |
| min_cpm        | BigDecimal | Minimum ad spend (USD, EU & UK data only) |
| max_cpm        | BigDecimal | Maximum ad spend (USD, EU & UK data only) |
| put_day        | Long       | Delivery days |
| start_time     | Long       | Ad start time (timestamp, seconds) |
| end_time       | Long       | Ad end time (timestamp, seconds) |

#### Response Example

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "data_count": 700,
    "adset_count": 150,
    "audience_reach": 15000000,
    "play_count": 6792774635,
    "min_cpm": 15.5,
    "max_cpm": 49.8,
    "put_day": 90,
    "start_time": 1685000000,
    "end_time": 1752202412
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 0,
  "success": true,
  "fail": false
}
```

---

## Error Code Descriptions

| Error Code | Description |
| ---------- | ----------- |
| 200        | Success |
| 400        | Request parameter error, such as missing store ID |
| 404        | Store does not exist |
| 500        | Internal server error |