# Store Product Analysis API Endpoint

## API Information

- **API Name**: Store Product Analysis API Endpoint
- **Request Method**: GET
- **API Address**: `/open-api/v1/data`
- **API Path**: `/v3/api/open/store/product-analysis`
- **API Description**:
    - Query product statistics and analysis data for a specified store
    - Statistics on the number of products promoted on different platforms, category distribution, and price range distribution
    - Support filtering product data by time range
    - Help analyze store product strategy and pricing strategy
    - Pricing: `Free`

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

### Request Body Parameters (params object)

| Parameter  | Type   | Required | Description                                                                                                          |
| ---------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------- |
| id         | string | true     | Store ID is a 13-character string (e.g., `c2d5b2547218a`), corresponding to the `store_id` field in the store rank list API response |
| start_time | long   | false    | Start time, timestamp (seconds), filters products by latest found time, if not provided, no start time limit        |
| end_time   | long   | false    | End time, timestamp (seconds), filters products by latest found time, if not provided, no end time limit            |


### 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/product-analysis",
    "params": {
      "id": "9407a696eb444",
      "start_time": 1761408000,
      "end_time": 1763999999
    }
  }'
```

## Response Parameters

### Response Body Structure

```json
{
    "code": 200,
    "message": "success",
    "data": {
        "total": {
            "all": 0,
            "total": 25,
            "tiktok": 25,
            "facebook": 0
        },
        "price": {
            "100": 4,
            "10-20": 0,
            "50-100": 16,
            "1-10": 0,
            "20-50": 5
        },
        "type": [
            {
                "ai_type_name_zh": "女装",
                "count": 12,
                "ai_type_name_en": "Women's Clothing",
                "ai_type": "62739c0138365b2f72048ed7"
            },
            {
                "ai_type_name_zh": "其他",
                "count": 2,
                "ai_type_name_en": "Other",
                "ai_type": "62739c2138365b2f72048edb"
            },
            {
                "ai_type_name_zh": "男装",
                "count": 2,
                "ai_type_name_en": "Men's Clothing",
                "ai_type": "62739c0d38365b2f72048ed8"
            }
        ]
    },
    "version": "v1",
    "timestamp": null,
    "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 0,
    "success": true,
    "fail": false
}
```

### Response Field Descriptions

| Field     | Type    | Description                       |
| --------- | ------- | --------------------------------- |
| code      | Integer | Response status code, 200 means success |
| message   | String  | Response message                  |
| data      | Object  | Response data                     |
| version   | String  | API version                       |
| timestamp | String  | 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        |

### Response Result Information Fields

| Field | Type   | Description             |
| ----- | ------ | ----------------------- |
| data  | Object | Product analysis data   |

#### data Object Structure

| Field | Type          | Description                        |
| ----- | ------------- | ---------------------------------- |
| total | Object        | Platform distribution statistics   |
| type  | Array[Object] | Product category statistics list   |
| price | Object        | Price range distribution statistics |

#### total Object Structure (Platform Distribution Statistics)

| Field    | Type | Description                                                  |
| -------- | ---- | ------------------------------------------------------------ |
| total    | Long | Total number of products                                     |
| tiktok   | Long | Number of products promoted on TikTok platform               |
| facebook | Long | Number of products promoted on Facebook platform             |
| all      | Long | Number of products promoted on both TikTok and Facebook      |

#### type Array Element Structure (Product Category)

| Field           | Type   | Description                    |
| --------------- | ------ | ------------------------------ |
| ai_type         | String | AI category type code          |
| ai_type_name_zh | String | AI category Chinese name       |
| ai_type_name_en | String | AI category English name       |
| count           | Long   | Number of products in this category |

#### price Object Structure (Price Range Distribution, Unit: USD)

| Field   | Type | Description                                    |
| ------- | ---- | ---------------------------------------------- |
| 1-10    | Long | Number of products in $1-$10 price range       |
| 10-20   | Long | Number of products in $10-$20 price range      |
| 20-50   | Long | Number of products in $20-$50 price range      |
| 50-100  | Long | Number of products in $50-$100 price range     |
| 100     | Long | Number of products with price ≥ $100           |


## Response Examples

### Complete Data Example

```json
{
    "code": 200,
    "message": "success",
    "data": {
        "total": {
            "all": 0,
            "total": 25,
            "tiktok": 25,
            "facebook": 0
        },
        "price": {
            "100": 4,
            "10-20": 0,
            "50-100": 16,
            "1-10": 0,
            "20-50": 5
        },
        "type": [
            {
                "ai_type_name_zh": "女装",
                "count": 12,
                "ai_type_name_en": "Women's Clothing",
                "ai_type": "62739c0138365b2f72048ed7"
            },
            {
                "ai_type_name_zh": "其他",
                "count": 2,
                "ai_type_name_en": "Other",
                "ai_type": "62739c2138365b2f72048edb"
            },
            {
                "ai_type_name_zh": "男装",
                "count": 2,
                "ai_type_name_en": "Men's Clothing",
                "ai_type": "62739c0d38365b2f72048ed8"
            }
        ]
    },
    "version": "v1",
    "timestamp": null,
    "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 0,
    "success": true,
    "fail": false
}
```

### Time Range Filter Example

Request parameters:
```json
{
  "id": "12345",
  "start_time": 1704067200,
  "end_time": 1706745599
}
```

Response data (only returns products found within the specified time range):
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "total": {
      "total": 125,
      "tiktok": 95,
      "facebook": 68,
      "all": 38
    },
    "type": [
      {
        "ai_type": "fashion",
        "ai_type_name_zh": "时尚服饰",
        "ai_type_name_en": "Fashion & Apparel",
        "count": 52
      },
      {
        "ai_type": "electronics",
        "ai_type_name_zh": "电子产品",
        "ai_type_name_en": "Electronics",
        "count": 38
      },
      {
        "ai_type": "beauty",
        "ai_type_name_zh": "美妆护肤",
        "ai_type_name_en": "Beauty & Personal Care",
        "count": 35
      }
    ],
    "price": {
      "100": 2,
      "1-10": 45,
      "10-20": 52,
      "20-50": 20,
      "50-100": 6
    }
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 0,
  "fail": false,
  "success": true
}
```

## Error Code Descriptions

| Error Code | Description           |
| ---------- | --------------------- |
| 200        | Success               |
| 400        | Request parameter error |
| 500        | Internal server error |

## Usage Instructions

### 1. Time Range Filtering

The API supports filtering products through `start_time` and `end_time` parameters:

- **Filter Dimension**: Product's latest found time (all_latest_found_time)
- **No time parameters**: Returns statistics for all products in the store
- **Only start_time**: Returns products found from that time point to now
- **Only end_time**: Returns products found from earliest to that time point
- **Both provided**: Returns products found within that time range

### 2. Platform Distribution Statistics Explanation

#### total Field Interpretation:
```json
{
  "total": 850,      // Store has promoted 850 products in total
  "tiktok": 620,     // Of which 620 products have ads on TikTok platform
  "facebook": 480,   // Of which 480 products have ads on Facebook platform
  "all": 250         // Of which 250 products have ads on both platforms
}
```

#### Relationship Explanation:
- `tiktok` + `facebook` - `all` = Number of products promoted on single platform only
- TikTok only: `tiktok - all` = 370 products
- Facebook only: `facebook - all` = 230 products
- Both platforms: `all` = 250 products
- Total: 370 + 230 + 250 = 850 products

### 3. Product Category Statistics Explanation

#### AI Smart Classification:
- System uses AI algorithms to automatically identify product categories
- Each product has corresponding category code and Chinese/English names
- Category statistics help understand store product structure

#### Common Categories:
- fashion: Fashion & Apparel
- electronics: Electronics
- home_garden: Home & Garden
- beauty: Beauty & Personal Care
- sports: Sports & Outdoors
- toys: Toys & Games
- food: Food & Beverages
- pet: Pet Supplies
- etc.

### 4. Price Range Distribution Explanation

#### Price Statistics Rules:
- Priority uses product's USD price (usd_price)
- If no USD price but currency is USD, uses original price (price)
- Other currencies are temporarily not counted

#### Price Range Division:
| Range Code | Price Range  | Applicable Scenarios              |
| ---------- | ------------ | --------------------------------- |
| 1-10       | $1 - $10     | Low-price items, small items      |
| 10-20      | $10 - $20    | Medium-low price items            |
| 20-50      | $20 - $50    | Medium price items                |
| 50-100     | $50 - $100   | Medium-high price items           |
| 100        | ≥ $100       | High-price items, luxury goods    |