适用场景
需要在服务端或脚本中获取中文地区天气数据时，最常见的诉求是：给定「省 + 市（可选区县）」，一次性拿到实时天气、空气质量、未来预报、生活指数与限行信息。腾讯天气接口以中文地名作为入参，省去了经纬度换算与地理编码的中间步骤，适合天气看板、出行提醒、值班日报等场景的快速接入。
本文围绕「最小可运行示例」展开：先用一条 curl 确认链路通，再用 Python 封装成函数，最后逐项核对返回字段。接口地址与方法以事实卡为准：
| 接口名称 | 腾讯天气 |
| 请求方法 | POST |
| 请求地址 | https://v1.apizero.cn/api/tencent-weather |
| 分类 | 生活服务 |
| QPS | 3 req/s |
| 鉴权 | Authorization: Bearer <API_KEY> |
接口能力边界
先明确这个接口能做什么、不能做什么，可以避免接入后反复改设计。
- 入参是中文名：province、city 为必填，county 可选，用于提升定位精度与限行准确度。
- 返回覆盖多个数据块：observe（实时）、air（空气质量）、daily_forecast（未来多天预报）、hourly_forecast（逐时预报）、life_index（生活指数）、sunrise_sunset（日出日落）、limit（机动车限行）、alarm（预警）。
- 数据来源为腾讯天气，字段含义与取值范围以官方文档为准，本文不承诺具体的数据刷新频率或覆盖范围。
- 该接口按 QPS 限流，调用方需要自行做节流与重试控制。
参数与鉴权
Query 参数
| province | 是 | string | 省 / 直辖市（中文名） | 广东 |
| city | 是 | string | 市（中文名） | 深圳 |
| county | 否 | string | 区 / 县（中文名），可提升定位精度与限行准确度 | 南山 |
请求体
请求体是一个 JSON 对象，字段与 Query 参数一致，province 与 city 必填，county 可选。注意请求方法为 POST，且 Content-Type 需要设置为 application/json。
鉴权
请求头使用 Bearer Token 形式携带密钥，密钥通过环境变量注入，避免硬编码进仓库：
export APIZERO_API_KEY="你的密钥"
最小可运行示例
curl 版本
以下示例可直接复制执行，其中地名按实际需要替换：
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 状态码，再看响应体中的 code 是否为 0，两者都满足再解析 data。
Python 版本
把请求封装为函数，便于后续在业务代码中复用：
import json
import os
import urllib.request
API_URL = "https://v1.apizero.cn/api/tencent-weather"
def query_tencent_weather(province: str, city: str, county: str | None = None) -> dict:
payload = {"province": province, "city": city}
if county:
payload["county"] = county
req = urllib.request.Request(
API_URL,
data=json.dumps(payload).encode("utf-8"),
headers={
"Authorization": f"Bearer {os.environ['APIZERO_API_KEY']}",
"Content-Type": "application/json",
},
method="POST",
)
with urllib.request.urlopen(req, timeout=10) as resp:
return json.loads(resp.read().decode("utf-8"))
if __name__ == "__main__":
result = query_tencent_weather("广东", "深圳", "南山")
print(result.get("code"), result.get("msg"))
print(result["data"]["observe"]["temperature"])
这段代码只依赖标准库，方便在没有第三方包的机器上验证连通性；正式项目中可换成任意 HTTP 客户端，请求结构与字段不变。
返回值解读
响应顶层包含 code、msg、request_id、tips，业务数据都在 data 下。以文档示例为例，逐块说明：
{
"code": 0,
"msg": "成功",
"request_id": "abc123",
"data": {
"observe": {"temperature": 30, "weather": "多云", "humidity": 77},
"air": {"aqi": 13, "pm25": 4, "pm10": 12, "quality": "优"},
"daily_forecast": [{"date": "2026-07-01", "temperature": {"max": 33, "min": 26}}],
"hourly_forecast": [{"time": "07-01 10:00", "temperature": 30, "weather": "多云"}],
"life_index": [{"key": "clothes", "name": "穿衣", "level": "炎热"}],
"limit": {"date": "2026-07-01", "tail_number": "3和8"},
"sunrise_sunset": [{"date": "2026-07-01", "sunrise": "05:43", "sunset": "19:12"}],
"alarm": [],
"location": {"province": "广东", "city": "深圳", "county": "南山"}
}
}
各数据块的用途如下：
- observe：实时观测，包含温度、天气、湿度、风向风力与更新时间，适合做「当前状态」展示。
- air：空气质量，aqi 为数值，quality 为中文等级，pm25、pm10 为颗粒物浓度。
- daily_forecast / hourly_forecast：分别对应按天与按小时的预报数组，数组长度与字段以文档为准。
- life_index：生活指数数组，通过 key 区分类型，如穿衣（clothes），level 为等级描述。
- limit：机动车限行信息，包含日期与限行尾号；提供 county 时准确度更高。
- sunrise_sunset：日出日落时间，按日期给出。
- alarm：天气预警数组，无预警时为空数组，解析时应按空数组处理而非当作缺失。
- location：回显本次查询的省市区，可用于确认中文名匹配是否正确。
常见错误与排查
| HTTP 401 | 请求头缺少 Bearer Token 或密钥无效 | 检查 Authorization 头与环境变量是否生效 |
| HTTP 404 / 405 | 方法或路径写错 | 确认使用 POST 与完整地址 |
| code 非 0 | 参数缺失或地名无法匹配 | 核对 province、city 是否为中文名，先不带 county 重试 |
| 返回 429 或限流提示 | 超过 QPS 限制 | 调用侧加并发控制与退避重试 |
| 限行信息为空 | 未传 county 或该地区无限行数据 | 补传区县后重试，并以文档说明为准 |
地名匹配是排查重点：中文名需与官方数据源一致，遇到同名市或直辖市区县时，补充 county 能减少歧义。
工程化注意事项
参考文档
- 文档页：https://apizero.cn/aidocs/tencent-weather
- 原始文档：https://apizero.cn/aidocs/tencent-weather/raw.md
