# 店铺产品分析接口

## 接口信息

- **接口名称**: 店铺产品分析接口
- **请求方法**: GET
- **接口地址**: `/open-api/v1/data`
- **接口路径**: `/v3/api/open/store/product-analysis`
- **接口描述**:
    - 查询指定店铺的产品统计分析数据
    - 统计店铺在不同平台推广的产品数量、分类分布和价格区间分布
    - 支持按时间范围筛选产品数据
    - 帮助分析店铺的产品策略和定价策略
    - 价格说明: `免费`

**请求头:**

- Content-Type: application/json
- Accept: application/json

## 请求参数

### 请求结构

| 参数名 | 类型   | 描述                        | 示例                                | 必填 | 默认值 |
| ------ | ------ | --------------------------- | ----------------------------------- | ---- | ------ |
| key    | string | 用户申请的外部 api 请求 key | "your_api_key_here"                 | 是   |        |
| uri    | string | 接口路径                    | "/v3/api/open/store/product-analysis"    | 是   |        |
| params | object | 接口入参对象                | 见参数列表                          | 是   |        |

### 请求体参数 (params 对象)

| 参数名     | 类型   | 必填  | 描述                                                         |
| ---------- | ------ | ----- | ------------------------------------------------------------ |
| id         | string | true  | 店铺 ID 为 13 位字符串（例如：`c2d5b2547218a`），对应店铺榜单列表接口返回结果中的 `store_id` 字段 |
| start_time | long   | false | 开始时间，时间戳（秒），筛选产品最新发现时间，不传则不限制开始时间 |
| end_time   | long   | false | 结束时间，时间戳（秒），筛选产品最新发现时间，不传则不限制结束时间 |


### 请求示例

```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
    }
  }'
```

## 响应参数

### 响应体结构

```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
}
```

### 响应字段说明

| 字段名    | 类型    | 描述                     |
| --------- | ------- | ------------------------ |
| code      | Integer | 响应状态码，200 表示成功 |
| message   | String  | 响应消息                 |
| data      | Object  | 响应数据                 |
| version   | String  | API 版本                 |
| timestamp | String  | 响应时间戳               |
| sign      | String  | 响应签名                 |
| remaining_credits | Long    | 当前请求后的剩余可用积分 |
| consumed_credits  | Long    | 本次请求消耗的积分 |
| success   | Boolean | 请求是否成功             |
| fail      | Boolean | 请求是否失败             |

### 响应结果信息字段

| 字段名 | 类型   | 描述             |
| ------ | ------ | ---------------- |
| data   | Object | 产品分析数据     |

#### data 对象结构

| 字段名 | 类型          | 描述                     |
| ------ | ------------- | ------------------------ |
| total  | Object        | 平台分布统计             |
| type   | Array[Object] | 产品分类统计列表         |
| price  | Object        | 价格区间分布统计         |

#### total 对象结构（平台分布统计）

| 字段名   | 类型 | 描述                                       |
| -------- | ---- | ------------------------------------------ |
| total    | Long | 总产品数量                                 |
| tiktok   | Long | 在 TikTok 平台推广的产品数量               |
| facebook | Long | 在 Facebook 平台推广的产品数量             |
| all      | Long | 同时在 TikTok 和 Facebook 推广的产品数量   |

#### type 数组元素结构（产品分类）

| 字段名           | 类型   | 描述                     |
| ---------------- | ------ | ------------------------ |
| ai_type          | String | AI 分类类型代码          |
| ai_type_name_zh  | String | AI 分类中文名称          |
| ai_type_name_en  | String | AI 分类英文名称          |
| count            | Long   | 该分类下的产品数量       |

#### price 对象结构（价格区间分布，单位：美元）

| 字段名  | 类型 | 描述                              |
| ------- | ---- | --------------------------------- |
| 1-10    | Long | 价格在 $1-$10 区间的产品数量      |
| 10-20   | Long | 价格在 $10-$20 区间的产品数量     |
| 20-50   | Long | 价格在 $20-$50 区间的产品数量     |
| 50-100  | Long | 价格在 $50-$100 区间的产品数量    |
| 100     | Long | 价格 ≥ $100 的产品数量            |


## 响应示例

### 完整数据示例

```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
}
```

### 按时间范围筛选示例

请求参数：
```json
{
  "id": "12345",
  "start_time": 1704067200,
  "end_time": 1706745599
}
```

响应数据（仅返回在指定时间范围内最新发现的产品）：
```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
}
```

## 错误码说明

| 错误码 | 描述           |
| ------ | -------------- |
| 200    | 成功           |
| 400    | 请求参数错误   |
| 500    | 服务器内部错误 |

## 使用说明

### 1. 时间范围筛选

接口支持通过 `start_time` 和 `end_time` 参数筛选产品：

- **筛选维度**：产品的最新发现时间（all_latest_found_time）
- **不传时间参数**：返回店铺所有产品的统计数据
- **只传 start_time**：返回从该时间点到现在发现的产品
- **只传 end_time**：返回从最早到该时间点发现的产品
- **都传**：返回该时间范围内发现的产品

### 2. 平台分布统计说明

#### total 字段解读：
```json
{
  "total": 850,      // 店铺总共推广了850个产品
  "tiktok": 620,     // 其中620个产品在TikTok平台有广告
  "facebook": 480,   // 其中480个产品在Facebook平台有广告
  "all": 250         // 其中250个产品同时在两个平台都有广告
}
```

#### 关系说明：
- `tiktok` + `facebook` - `all` = 只在单一平台推广的产品数
- 只在 TikTok：`tiktok - all` = 370个
- 只在 Facebook：`facebook - all` = 230个
- 两平台都有：`all` = 250个
- 总计：370 + 230 + 250 = 850个

### 3. 产品分类统计说明

#### AI 智能分类：
- 系统使用 AI 算法自动识别产品类别
- 每个产品都有对应的分类代码和中英文名称
- 分类统计帮助了解店铺的产品结构

#### 常见分类：
- fashion：时尚服饰
- electronics：电子产品
- home_garden：家居园艺
- beauty：美妆护肤
- sports：运动户外
- toys：玩具游戏
- food：食品饮料
- pet：宠物用品
- etc.

### 4. 价格区间分布说明

#### 价格统计规则：
- 优先使用产品的美元价格（usd_price）
- 如果没有美元价格但货币为 USD，使用原价格（price）
- 其他货币暂不统计

#### 价格区间划分：
| 区间代码 | 价格范围     | 适用场景                 |
| -------- | ------------ | ------------------------ |
| 1-10     | $1 - $10     | 低价商品、小件商品       |
| 10-20    | $10 - $20    | 中低价商品               |
| 20-50    | $20 - $50    | 中等价位商品             |
| 50-100   | $50 - $100   | 中高价商品               |
| 100      | ≥ $100       | 高价商品、奢侈品         |