最小可运行示例：腾讯天气 API 接入与参数解析

适用场景腾讯天气 API 适合需要获取国内任意城市支持省、市、区县三级实时天气与预报信息的场景。典型应用包括移动端天气 app 的后台数据源智能家居设备如智能音箱、智能屏的天气播报活动策划、户外出行前的天气风险评估企业内部系统的天气告警如高温、暴雨预警结合生活指数为用户提供穿衣、洗车、运动等建议该接口最大的特点是直接使用中文地名无需将城市名转换为经纬度或城市编码降低了预处理维护复杂度。接口能力边界请求方式POST请求地址https://v1.apizero.cn/api/tencent-weatherQPS 限制10 次/秒超出可能返回限流错误调用额度未登录状态每日 500 次登录认证后每日 1000 次数据来源腾讯天气官方数据源包括实时观测、未来 7 天逐日预报、24 小时逐时预报、空气质量AQI/PM2.5/PM10、23 项生活指数、日出日落时间以及机动车限行信息。注意QPS 和每日额度为平台限制实际调用时请做好本地节流与重试逻辑。参数与鉴权Header 参数参数名类型必填说明Authorizationstring否Bearer 你的 API Key。如果不传以未登录用户身份调用额度 500 次/日传入有效 Key 后按登录用户额度1000 次/日计数。实际请求中如需使用登录额度可将 API Key 通过环境变量或配置文件注入避免硬编码。请求体JSON字段名类型必填描述示例provincestring是省份或直辖市的中文全称广东citystring是地级市的中文全称深圳countystring否区县中文名称可提升定位精度和限行信息的准确度南山最小可运行的 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说明示例中使用X-API-Key头部传递 API Key与Authorization: Bearer两种方式均可。实际使用时只需选择一种。$APIZERO_API_KEY需替换为你从控制台获取的 Key。其他语言接入示例Pythonimport requests import json url https://v1.apizero.cn/api/tencent-weather headers { X-API-Key: your_api_key_here, Content-Type: application/json } payload { province: 广东, city: 深圳, county: 南山 } try: resp requests.post(url, headersheaders, jsonpayload, timeout10) resp.raise_for_status() data resp.json() print(json.dumps(data, indent2, ensure_asciiFalse)) except requests.exceptions.RequestException as e: print(f请求异常: {e})返回值解读成功响应示例状态码 200结构如下{ code: 0, msg: 成功, request_id: abc123, data: { location: { province: 广东, city: 深圳, county: 南山 }, observe: { temperature: 30, weather: 多云, humidity: 77, wind_direction: 北风, wind_power: 3-4, update_time: 2026-07-01 10:15 }, air: { aqi: 13, level: 1, quality: 优, pm25: 4, pm10: 12 }, 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: 炎热, detail: 建议穿着轻薄衣物... } ], sunrise_sunset: [ { date: 2026-07-01, sunrise: 05:43, sunset: 19:12 } ], limit: { date: 2026-07-01, tail_number: 3和8 }, alarm: [] } }字段含义顶层字段字段类型说明codeint业务状态码0 表示成功非 0 见常见错误msgstring状态描述request_idstring请求唯一标识可用于排查问题dataobject核心天气数据data 内部字段location请求的地理位置回显用于确认接口解析的省市区。observe当前实时观测数据。temperature当前温度摄氏度weather天气现象中文名humidity湿度百分比wind_direction风向wind_power风力等级如 3-4 表示 3 到 4 级update_time观测时间air空气质量信息。aqi空气质量指数level等级1-6数值越小越好quality文字描述优、良等pm25/pm10颗粒物浓度μg/m³daily_forecast未来 7 天逐日预报数组。date日期 yyyy-MM-ddtemperature.max最高温temperature.min最低温注意示例中仅展示部分字段实际返回可能包含weather、wind等以文档为准。hourly_forecast24 小时逐时预报数组。time格式 MM-dd HH:mmtemperature整点温度weather天气现象life_index生活指数数组。key英文标识如 clothes、uv、car_washname中文名称level等级描述detail详细建议sunrise_sunset日出日落时间数组未来 7 天。date日期sunrise/sunset时间 HH:mmlimit限行信息仅限已实施限行的城市。date日期tail_number限行尾号如 3和8alarm气象预警数组。通常为预警对象列表若无预警则为空数组。常见错误与处理错误场景返回表现处理方式缺少必填参数province或citycode 非 0msg 提示参数缺失检查请求体 JSON 结构不合法的中文地名code 非 0如 查询不到该城市信息使用省级行政区划标准名称勿用简称API Key 无效或过期401 Unauthorized检查 Key 是否复制完整或重新生成超出 QPS 限制返回限流错误通常为 429加入队列或 sleep 间隔 100ms每日额度耗尽返回额度超限错误升级认证或等待次日重置建议在代码中统一处理code ! 0的分支并根据msg给出日志或用户提示。工程化注意事项缓存策略实时天气和预报类数据更新频率通常为 30 分钟至 1 小时。可在服务端设置缓存如 Redis对相同城市请求设置 TTL减少重复调用。错误重试网络波动或服务器临时故障时实现指数退避重试如 1s、2s、4s最多 3 次。地域兜底若用户只提供省和市可将county留空接口会自动解析到市级。但若要获取精准限行信息建议尽量传入区县。时区处理接口返回的时间均为北京时间UTC8无需额外转换。但跨时区系统展示时需注意。字段变更API 响应结构可能随着腾讯天气数据源更新而微调。建议在消费端记录 JSON Schema 并做好字段兼容例如使用动态字段解析。限流防护虽然 QPS 为 10但建议客户端将请求分散到不同时刻避免集中调用导致 429。参考文档腾讯天气 API 官方文档包含原始 JSON 定义与更新日志