适用场景当需要在应用中展示实时天气、未来预报、空气质量或生活指数时腾讯天气API提供了一套免经纬度、中文省市名直接查询的解决方案。适用场景包括个人小工具如桌面天气助手、定时推送天气提醒企业应用物流配送的天气风险预警、户外活动安排智能硬件联动智能家居根据天气调整温控策略限行查询输入区县后可获取机动车尾号限行信息接口能力边界腾讯天气API支持以下数据维度实时天气温度、湿度、风向风力、天气现象空气质量AQI、PM2.5、PM10、等级及文字描述未来7天预报每日最高/最低温度、天气状况24小时逐时预报每小时的温度和天气23项生活指数穿衣、紫外线、洗车、感冒等日出日落当日及后续日期的日出日落时间机动车限行基于区县精度返回尾号限行信息天气预警如果发布会包含预警列表示例中为空数组接口的QPS限制为10次/秒单次调用返回全部上述数据。未携带API Key时每日500次额度携带Key后提升至每日1000次。请求参数与鉴权Header参数参数名类型必填说明Authorizationstring否Bearer 你的API Key携带后获得更高每日额度X-API-Keystring否与Authorization二选一部分代理支持此头注意两种鉴权方式都是可选的不携带也能调用但额度较低。示例使用X-API-Key头以保持与平台文档一致实际建议用Authorization: Bearer。请求体JSON字段名类型必填说明示例provincestring是省/直辖市中文名广东citystring是市中文名深圳countystring否区/县中文名提升限行准确性南山请求体必须为JSON对象内容类型application/json。最小可运行示例curl命令以下命令直接复制到终端即可运行需替换$APIZERO_API_KEY为你自己的Keycurl -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如果未申请Key可移除-H X-API-Key: $APIZERO_API_KEY行使用匿名额度每日500次。使用Authorization头的等效写法curl -sS \ -X POST \ -H Authorization: Bearer YOUR_API_KEY \ -H Content-Type: application/json \ -d {province: 北京, city: 北京市, county: 海淀} \ https://v1.apizero.cn/api/tencent-weather返回字段全解读成功响应HTTP状态码200JSON结构如下{ code: 0, msg: 成功, request_id: abc123, data: { location: { ... }, observe: { ... }, air: { ... }, daily_forecast: [ ... ], hourly_forecast: [ ... ], life_index: [ ... ], sunrise_sunset: [ ... ], alarm: [ ... ], limit: { ... } } }顶层字段code0为成功其他值见错误码说明msg描述信息request_id请求标识用于排查问题data数据主体data.location查询位置{ province: 广东, city: 深圳, county: 南山 }返回实际查询的省市县可用于确认请求参数是否正确。data.observe实时观测字段类型说明temperaturenumber当前温度摄氏度humiditynumber相对湿度%weatherstring天气现象描述wind_directionstring风向wind_powerstring风力等级update_timestring数据更新时间格式yyyy-MM-dd HH:mmdata.air空气质量字段类型说明aqinumber空气质量指数levelnumber等级1-6pm25numberPM2.5浓度μg/m³pm10numberPM10浓度μg/m³qualitystring文字评价优/良/轻度污染等data.daily_forecast7天预报数组元素结构{ date: 2026-07-01, temperature: { max: 33, min: 26 }, weather: 多云 }注实际返回还包含更多字段如风向、风力等以平台文档为准。data.hourly_forecast24小时逐时预报数组元素{ time: 07-01 10:00, temperature: 30, weather: 多云 }时间格式为MM-dd HH:mm不包含年份。data.life_index23项生活指数示例{ key: clothes, name: 穿衣, level: 炎热, detail: 建议穿轻棉织物制作的短衣、短裙、短裤…… }常用key包括clothes,uv,car_wash,cold,sport,travel等详见文档。data.sunrise_sunset日出日落{ date: 2026-07-01, sunrise: 05:43, sunset: 19:12 }逐日数据数组长度与daily_forecast一致。data.alarm预警数组有预警时包含对象无预警为空数组[]。预警字段结构以文档为准。data.limit限行信息仅在提供county参数且该区域实施限行时返回。示例{ date: 2026-07-01, tail_number: 3和8 }表示当日限行尾号为3和8。常见错误与排查HTTP状态码codemsg 含义可能原因200非0城市不存在province或city参数与官方行政区划不符建议使用“北京/北京市”而非“北京/北京”200非0缺少必要参数province或city未传或为空401-未授权使用了无效的API Key格式若携带了Key429-请求过多超过10次/秒的QPS限制需要做限流或退避500-服务端错误临时问题可重试排查步骤先用不带Key的curl测试排除鉴权问题确认城市名使用标准名称如“广东-深圳-南山”正确“广东-东莞市”正确地级市直接写city检查JSON语法确保使用双引号无多余逗号查看响应中request_id可用于向平台反馈工程化注意事项缓存策略天气数据变化较慢建议对同一城市缓存5-10分钟减少调用次数。尤其逐时预报和7天预报每小时更新一次即可。限流控制QPS10意味着每100ms最多一次请求。若业务需要频繁查询多个城市可在代码中维护请求队列或使用令牌桶。必填参数验证后端在发起请求前应对province和city做非空校验避免浪费配额。异常重试HTTP 5xx或网络超时后采用指数退避重试例如1s, 2s, 4s。注意不要对4xx错误重试。County参数选择若需要限行信息务必传入county若只需天气可不传以节省请求体积。数据类型处理temperature、aqi等数值字段直接使用数字无需额外转换wind_power为字符串如“3-4”前端展示时需注意。参考文档腾讯天气API官方文档原始Markdown文档本文基于API事实卡创作所有参数与字段均以官方文档为准。