---
name: gotohui-data
description: 通过聚汇数据开放 API 查询中国城市/省份/国家的宏观经济数据（GDP、人口、房价、CPI 等）。当用户询问宏观经济指标、需要历年数据序列或数据分析素材时使用。搜索免费，获取数值按数据买断限期访问权限（与站内购买同一权限，有效期天数见 /me 的 access_validity_days）。
---

# 聚汇数据开放 API

聚汇数据（gotohui.com）提供中国及全球区域的宏观经济数据查询。本技能通过 HTTP 调用其开放接口。

## 鉴权

所有请求携带 API Key（在聚汇数据「会员中心 → 开放 API」创建）：

```
Authorization: Bearer {GOTOHUI_API_KEY}
```

Key 从环境变量 `GOTOHUI_API_KEY` 读取（仅支持请求头传参，不支持 `?api_key=` query）。

## 接口（Base URL: https://www.gotohui.com/api/open/v1）

### 1. 搜索数据（免费）

```
GET /search?word={关键词}&channel=data&page=1
```

- `word`：单关键词，至少 2 个字，如 `北京 GDP`
- `channel`：`data`=宏观数据（默认）/ `community`=社区文章
- 可选过滤：`category_id`（ID 见 `/meta/categories`）、`period`（year/quarter/month）、`limit`（≤50）

返回 `data.list[]`：`{id, name, unit, region_id, category_id, period_type, start_year, end_year, data_range}`。记住 `id`，取数用。

**多关键词批量（推荐，省调用次数）**：一次搜多个指标用 `words`，每个词各自返回上限条、互不挤占（解决"固定单页上限被多词稀释"）：

```
# REST：words[] 数组，或逗号/中文逗号分隔
GET /search?words[]=北京GDP&words[]=上海GDP&channel=data
GET /search?words=北京GDP,上海GDP,广州GDP&channel=data
```

返回按词分组（不再是平铺 list）：

```json
{
  "status": 200,
  "data": {
    "channel": "data", "per_word": 8, "word_count": 3,
    "groups": [
      { "word": "北京GDP", "total": 137, "list": [ {"id": 88421, "name": "北京地区生产总值", ...} ] },
      { "word": "上海GDP", "total": 120, "list": [ ... ] },
      { "word": "某冷门词", "total": 0, "list": [] }
    ]
  }
}
```

- `words` 与 `word` 二选一；`words` 非空时走批量分组、忽略 `word`/`page`
- 单次最多 10 个词、每词最多 8 条（上限可由站点后台调整）；忽略大小写去重
- 个别词搜不到 → 该组 `list:[]`（正常，不报错）；个别词后端出错 → 该组带 `"error":"搜索失败"`，不影响其它词

### 2. 获取数据数值（授权后买断限期访问权限）

```
GET /data/{id}            # 第一步：报价（未购数据返回 need_authorization，不扣分）
GET /data/{id}?confirm=1  # 第二步：用户同意后确认购买，返回数值
```

**🔴 授权后购买（两步）**：未购买的数据，第一步**不带 `confirm`** 时只返回报价、不扣分、不返数值——你必须先把成本与余额告知用户，取得用户明确同意后，第二步带 `confirm=1` 重新调用才真正扣分取数。

报价响应（第一步）：

```json
{
  "status": 200,
  "data": {
    "need_authorization": true, "code": 503009,
    "id": 88421, "name": "北京地区生产总值", "unit": "亿元",
    "points_cost": 1, "points_balance": 499, "charged": false,
    "message": "获取「北京地区生产总值」需消耗 1 积分买断 365 天访问权限，当前余额 499。确认后请带 confirm=true 重新调用。"
  }
}
```

数值响应（第二步 `confirm=1`，或数据已购）：

```json
{
  "status": 200,
  "data": {
    "id": 88421, "name": "北京地区生产总值", "unit": "亿元", "period_type": "year",
    "values": [ {"period": "2025", "value": "49843.10", "calc_value": "5.20"}, ... ],
    "points_cost": 1, "charged": true, "points_balance": 498
  }
}
```

- `values[]` 从新到旧；`calc_value` 是同比增速（%），无则为 null
- **计费（与聚汇数据站内购买同一套权限）**：确认后消耗积分（单价见 `/me`）自动买断该数据
  **限期不限次访问权限**（有效期天数见 `/me` 的 `access_validity_days`），网站详情页同步解锁；期内重复获取免费（`charged=false`、无需 `confirm`），到期后需重新购买；
  已在站内购买过的数据（单条或所属区域权限）直接返回、免确认免扣
- 价格由站点后台配置；配置异常（缺失或 ≤0）时接口直接报错，不会免费放行

### 3. 搜索排行榜（免费）

```
GET /ranking/list?word={关键词}&category_id={可选}&page=1
```

- `word`：可选，关键词匹配榜单标题，如 `GDP`、`人口`
- 免费/付费榜均返回（`is_paid` 仅为标记，取榜全部免费）。返回 `data.list[]`：`{slug, title, unit, region_level, is_paid}`。记住 `slug`，取榜用。

### 4. 获取榜单完整数据（免费，仅最新年）

```
GET /ranking/{slug}
```

返回最新年份完整排名序列 `data.list[]`：`{rank, region_id, region_name, value, unit, trend}`，外加 `{slug, title, unit, is_paid, year, total}`。

- **全部免费**：付费榜/免费榜均直接返回全量，无报价/确认步骤（与网站榜单页口径一致——榜单默认年份整榜公开，付费榜仅历史年份才需解锁）
- 仅提供最新年份；`year` 参数已下线，显式传年会报错

### 5. 房价查询（免费）

```
GET /house-price?region={区域}&year={可选}&month={可选}
```

- `region`：必填，区域名称（如 `深圳`、`杭州余杭`），或直接传 `region_id` 数字
- `year`+`month`：可选，须成对提供；**缺省取该区域最新有数据的月份**；**时间不能超过当前月份**
- 数据来自房价月度历史表，免费、不消耗积分；走**独立限流档**（与其它接口分开计数，额度见 `/me` 的 `house_price_*`）

命中单一区域且有数据时返回：

```json
{
  "status": 200,
  "data": {
    "region_id": 440300, "region_name": "深圳", "year": 2025, "month": 3, "period": "2025-03",
    "has_data": true, "unit": "元/㎡",
    "second_hand_price": 65000.00, "second_hand_total_price": 650.00,
    "second_hand_price_yoy": -5.20, "second_hand_price_mom": -0.80,
    "new_house_price": 58000.00, "new_house_total_price": 580.00,
    "new_house_price_yoy": -3.10, "new_house_price_mom": -0.50,
    "rent_monthly": 75.00, "rent_yield": 1.38,
    "data_source": "国家统计局", "latest_period": "2025-03"
  }
}
```

- 区域名称匹配到多个时返回候选（不返价）：`{ambiguous:true, message, candidates:[{region_id, region_name, parent_region, region_level}]}`，再用 `region_id` 指定其一
- 该月无数据 / 时间超过当前月 / 时间参数非法时返回 `{has_data:false, message, latest_period}`，按 `latest_period` 改取可用月份

### 6. 获取社区文章（免费）

```
GET /community/{id}
```

返回 `{id, title, summary, content, tags[], category_id, region_id, data_id, publish_time, view_count}`。`content` 为正文纯文本。文章 ID 来自搜索（`channel=community`）结果。免费，仅受限流约束。

### 7. 账户自检（免费）

```
GET /me
```

返回 `{points_balance, data_points_cost, access_validity_days, daily_limit, daily_used, qps_limit, house_price_daily_limit, house_price_daily_used, house_price_qps_limit}`。`data_points_cost` 是买断一条数据访问权限的积分价，`access_validity_days` 是权限有效期天数。`house_price_*` 是房价接口**独立限流档**的额度与已用（房价单独计数，不占用其它接口的日上限）。批量取数前先确认余额。

### 8. 字典（免费）

```
GET /meta/categories           → {categories[]}   # 顶级数据分类，供 /search 的 category_id 过滤
```

## 响应约定

- 统一信封：`{status, msg, data}`，HTTP 状态码恒为 200，以 body 的 `status` 为准（200 成功 / 400 失败 / 401 鉴权失败）
- 业务错误带 `code` 字段，机读处理：

| code | 含义 | 建议处理 |
|------|------|---------|
| 503001 | API Key 无效或已禁用 | 提示用户检查 Key |
| 503002 | 积分不足 | 提示用户前往聚汇数据会员中心充值，不要重试 |
| 503003 | QPS 超限 | 等待 1 秒后重试 |
| 503004 | 今日调用次数已达上限 | 停止调用，明日再试 |
| 503005 | 数据不存在 | 检查 id 是否来自搜索结果 |
| 503006 | 关键词过短 | 关键词至少 2 个字 |
| 503007 | 服务暂时不可用 | 稍后重试，连续失败则放弃 |
| 503009 | 需授权后购买（报价信号） | 出现在取数的报价响应里（非错误）：向用户说明积分成本，同意后带 `confirm=1`/`confirm=true` 重新调用 |

## 推荐工作流

1. `GET /me` 确认余额（可选）
2. `GET /search?words=A,B,C` 一次批量定位多个指标，向用户展示候选项
3. `GET /data/{id}` 取报价（`need_authorization`：所需积分 + 余额），**向用户说明成本并征得同意**
4. 用户同意后 `GET /data/{id}?confirm=1` 真正购买取数（已购数据可跳过 2-3 步直接拿数值）
5. 基于 `values[]` 做分析、对比、图表

## 注意

- 搜索翻页、换关键词、批量搜词都免费，放心多试；取数才扣积分（买断该数据限期访问权限）
- **取数遵循"授权后购买"**：未购数据第一次调用只返回报价（`need_authorization`），必须先把所需积分与余额告知用户、征得同意，再带 `confirm=1`/`confirm=true` 重新调用才扣分
- 已购数据有效期内可反复取（不重复扣费），无需本地缓存
- QPS 默认 2 次/秒，批量取数请串行执行