# 店铺地区广告分析接口

## 接口信息

- **接口名称**: 店铺地区广告分析接口
- **请求方法**: GET
- **接口地址**: `/open-api/v1/data`
- **接口路径**: `/v3/api/open/store/storeRegionAnalysis`
- **接口描述**:
    - 获取指定店铺在各个平台各个地区的广告投放数量统计
    - 通过店铺ID(id)查询该店铺在 TikTok、Facebook 和 Meta 广告资料库三个平台的地区分布数据
    - 价格说明: `免费`

**请求头:**

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

## 请求参数

### 请求结构

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

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

| 参数名 | 类型   | 必填 | 描述   |
| ------ | ------ | ---- | ------ |
| id     | string | true | 店铺 ID 为 13 位字符串（例如：`c2d5b2547218a`），对应店铺榜单列表接口返回结果中的 `store_id` 字段。 |


### 请求示例

```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/storeRegionAnalysis",
    "params": {
      "id": "9407a696eb444"
    }
  }'
```

## 响应参数

## 响应示例

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "facebook_library_regions": [
      {
        "count": 58823,
        "region": "OTHER"
      },
      {
        "count": 20260,
        "region": "US"
      },
      {
        "count": 17957,
        "region": "JP"
      },
      {
        "count": 12519,
        "region": "AU"
      },
      {
        "count": 11868,
        "region": "GB"
      },
      {
        "count": 8193,
        "region": "KR"
      },
      {
        "count": 7279,
        "region": "FR"
      },
      {
        "count": 6105,
        "region": "DE"
      },
      {
        "count": 5345,
        "region": "CA"
      },
      {
        "count": 3886,
        "region": "AE"
      },
      {
        "count": 2539,
        "region": "SA"
      },
      {
        "count": 2075,
        "region": "TH"
      },
      {
        "count": 1509,
        "region": "MY"
      },
      {
        "count": 1171,
        "region": "MX"
      },
      {
        "count": 453,
        "region": "PL"
      },
      {
        "count": 398,
        "region": "NL"
      },
      {
        "count": 364,
        "region": "ID"
      },
      {
        "count": 211,
        "region": "BE"
      },
      {
        "count": 196,
        "region": "AT"
      },
      {
        "count": 196,
        "region": "SE"
      },
      {
        "count": 189,
        "region": "VN"
      },
      {
        "count": 107,
        "region": "IT"
      },
      {
        "count": 76,
        "region": "PH"
      },
      {
        "count": 69,
        "region": "FI"
      },
      {
        "count": 24,
        "region": "ES"
      },
      {
        "count": 23,
        "region": "IE"
      },
      {
        "count": 22,
        "region": "DK"
      }
    ],
    "facebook_regions": [
      {
        "count": 219,
        "region": "US"
      },
      {
        "count": 61,
        "region": "TH"
      },
      {
        "count": 56,
        "region": "DE"
      },
      {
        "count": 51,
        "region": "CA"
      },
      {
        "count": 49,
        "region": "VN"
      },
      {
        "count": 43,
        "region": "FR"
      },
      {
        "count": 38,
        "region": "GB"
      },
      {
        "count": 30,
        "region": "TW"
      },
      {
        "count": 21,
        "region": "ID"
      },
      {
        "count": 15,
        "region": "JP"
      },
      {
        "count": 12,
        "region": "MY"
      },
      {
        "count": 11,
        "region": "IT"
      },
      {
        "count": 9,
        "region": "HK"
      },
      {
        "count": 8,
        "region": "KR"
      },
      {
        "count": 7,
        "region": "AU"
      },
      {
        "count": 5,
        "region": "SG"
      },
      {
        "count": 5,
        "region": "PH"
      },
      {
        "count": 5,
        "region": "NL"
      },
      {
        "count": 3,
        "region": "ES"
      },
      {
        "count": 2,
        "region": "NZ"
      },
      {
        "count": 2,
        "region": "CH"
      },
      {
        "count": 2,
        "region": "CN"
      },
      {
        "count": 2,
        "region": "PL"
      },
      {
        "count": 1,
        "region": "FI"
      },
      {
        "count": 1,
        "region": "PT"
      },
      {
        "count": 1,
        "region": "GR"
      },
      {
        "count": 1,
        "region": "MX"
      },
      {
        "count": 1,
        "region": "LA"
      },
      {
        "count": 1,
        "region": "NG"
      },
      {
        "count": 1,
        "region": "TR"
      }
    ],
    "tiktok_region": [
      {
        "count": 10835,
        "region": "SG"
      },
      {
        "count": 7051,
        "region": "TH"
      },
      {
        "count": 6534,
        "region": "MY"
      },
      {
        "count": 4795,
        "region": "VN"
      },
      {
        "count": 4553,
        "region": "ID"
      },
      {
        "count": 2296,
        "region": "TW"
      },
      {
        "count": 1679,
        "region": "JP"
      },
      {
        "count": 1268,
        "region": "PH"
      },
      {
        "count": 825,
        "region": "CA"
      },
      {
        "count": 718,
        "region": "AU"
      },
      {
        "count": 569,
        "region": "KR"
      },
      {
        "count": 115,
        "region": "US"
      },
      {
        "count": 95,
        "region": "FR"
      },
      {
        "count": 92,
        "region": "NL"
      },
      {
        "count": 66,
        "region": "NO"
      },
      {
        "count": 42,
        "region": "SA"
      },
      {
        "count": 37,
        "region": "DE"
      },
      {
        "count": 36,
        "region": "AE"
      },
      {
        "count": 28,
        "region": "TR"
      },
      {
        "count": 24,
        "region": "GR"
      },
      {
        "count": 22,
        "region": "GB"
      },
      {
        "count": 16,
        "region": "DK"
      },
      {
        "count": 13,
        "region": "PT"
      },
      {
        "count": 13,
        "region": "SC"
      },
      {
        "count": 9,
        "region": "IT"
      },
      {
        "count": 8,
        "region": "MX"
      },
      {
        "count": 5,
        "region": "BE"
      },
      {
        "count": 5,
        "region": "BR"
      },
      {
        "count": 4,
        "region": "RO"
      },
      {
        "count": 3,
        "region": "AT"
      },
      {
        "count": 3,
        "region": "PL"
      },
      {
        "count": 2,
        "region": "ES"
      },
      {
        "count": 1,
        "region": "CZ"
      }
    ]
  },
  "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 | 请求是否失败             |

### 响应结果信息字段

| 字段名                      | 类型          | 描述                                    |
|--------------------------| ------------- | --------------------------------------- |
| facebook_library_regions | Array[Region] | Meta 广告资料库各地区广告数量统计       |
| facebook_regions         | Array[Region] | Facebook 平台各地区广告数量统计         |
| tiktok_regions           | Array[Region] | TikTok 平台各地区广告数量统计           |

#### Region 对象结构

| 字段名 | 类型   | 描述                            |
| ------ | ------ | ------------------------------- |
| region | String | 地区简写代码，如 US、GB、DE、IT |
| count  | Long   | 该地区对应的广告数量            |


## 错误码说明

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