数据面与调用面：腾讯天气接口的能力边界与适用场景

从需求出发：什么时候值得调用这个接口

在接入一个天气数据源之前，先回答两个问题：业务真正需要哪几个字段？这些字段能容忍多大的延迟与误差？腾讯天气接口用中文省市名直接查询，把地理编码过程收敛在服务端，客户端不需要维护经纬度到城市的映射表，这是它在“按城市名取数”场景下的核心价值。

典型适用场景：

1. 城市级展示型应用：后台管理系统的天气看板、运营活动页的天气模块，只需要城市维度的实时温度、天气现象和未来几天趋势。
2. 生活信息聚合：把穿衣、紫外线、运动等指数挂在城市页面上，作为增值信息。
3. 限行提示：响应中携带机动车尾号限行信息，可嵌入车主服务或出行提醒。
4. 轻量级数据采集：定时抓取目标城市空气质量与逐时预报，做本地存储和趋势计算。

接口能力边界

能返回什么

通过一次 POST 请求，响应体 data 字段内包含以下数据块：

不能做什么

• 接口不接收经纬度参数，只接受中文省市名，所以无法精确到街道级别的天气查询。
• 接口 QPS 上限为 10/s，是共享约束；短时间突发大量请求会触发限流。
• 默认额度为未登录 500 次/日，登录用户 1000 次/日，这是账号级配额，响应体中不返回剩余额度，需要在业务侧自行计数。
• 省市名必须使用规范中文名称，缩写或拼音（如 “gd”、“sz”）不会得到预期结果。
• county 为可选参数，但如果不传，限行信息和部分生活指数的确定性会下降。

以上边界决定：该接口适合“按城市聚合信息”，不适合“按坐标做个性化天气”。

请求参数与鉴权方式

请求方法为 POST，Content-Type 为 application/json，请求体是一个 JSON 对象：

鉴权方面，接口文档的 Header 参数说明中，Authorization 为可选请求头，格式为 Bearer <你的 API Key>；curl 示例则使用 X-API-Key 请求头。两者指向同一个 Key，接入时按文档页给出的形式选用即可。

用 curl 打通请求链路

curl -sS \
  -X POST \
  -H "X-API-Key: $APIZERO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"province": "广东", "city": "深圳", "county": "南山"}' \
  "https://v1.apizero.cn/api/tencent-weather"

将 $APIZERO_API_KEY 替换为自己的 API Key。若使用 Authorization 风格：

curl -sS \
  -X POST \
  -H "Authorization: Bearer $APIZERO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"province": "广东", "city": "深圳", "county": "南山"}' \
  "https://v1.apizero.cn/api/tencent-weather"

返回结构解读

成功时 HTTP 状态码为 200，响应顶层字段包括 code、msg、request_id 与 data。code 为 0 表示业务成功。整体结构如下：

{
  "code": 0,
  "msg": "成功",
  "request_id": "abc123",
  "data": {
    "observe": {},
    "air": {},
    "daily_forecast": [],
    "hourly_forecast": [],
    "life_index": [],
    "sunrise_sunset": [],
    "limit": {},
    "alarm": [],
    "location": {}
  }
}

data 中的关键字段再展开说明：

• observe：实时观测数据，update_time 标注数据时间，缓存判断应以此字段为准。
• air：level 为空气质量等级数值，quality 为文字描述。
• daily_forecast：示例只列出 date 与 temperature，完整字段以文档为准。
• hourly_forecast：time 为 “MM-DD HH:mm” 格式字符串，跨年比对时注意补全年份。
• life_index：共 23 项，每项含 key、name、level、detail。
• limit：tail_number 为限行尾号，date 为生效日期。
• alarm：无预警时返回空数组。
• sunrise_sunset：日出日落时间为字符串格式。

常见错误与排查切入点

接口文档未给出完整错误码表，这里从请求链路常见故障现象出发给出排查方向：

1. HTTP 401：API Key 缺失或无效，检查请求头名称与值是否正确。
2. HTTP 429 或 code 非 0：触发 QPS 上限或每日配额用尽，需要执行退避重试或等待配额恢复。
3. location 字段与请求不符：省市县名称写法不规范，检查是否为标准中文称谓。
4. 响应超时或偶发空数据：天气数据依赖上游数据源，建议设置超时时间与指数退避重试。

工程化注意事项

• 缓存：天气数据分钟级变化，设置 5 到 10 分钟的 TTL 能显著减少请求量。
• 限流：业务侧实现本地令牌桶或信号量，避免单机突发打到 10 QPS 上限。
• 配额监控：在服务端统计每日请求数，接近上限时降级为缓存数据或备用源。
• 参数白名单：在调用前置步骤校验省份、城市名，减少无效请求。
• 日志与链路追踪：保存 request_id，出现异常时可向平台反馈排查。

参考文档

接口文档页：https://apizero.cn/aidocs/tencent-weather

原始文档：https://apizero.cn/aidocs/tencent-weather/raw.md