接口概述彩云天气 API 基于彩云 v2.6 协议封装提供实时天气、分钟级降水、逐小时和逐天预报、气象预警以及生活指数等全量数据。它支持城市名称或经纬度坐标两种查询方式内置约 140 个常用中国城市表同时依赖 Open-Meteo 进行兜底解析无需额外地理编码 Key。返回数据中的天气现象、风向、风级、AQI 等级等字段均自动转为中文可读形式大大降低了二次解析的负担。适用场景移动端天气应用一次请求获取实时 预报 预警减少客户端并发。智能家居/户外活动决策利用分钟级降水判断未来两小时是否需要关窗或带伞。农业/物流监控逐天预报配合日出日落、温度极值规划灌溉或运输窗口。数据可视化大屏使用summary字段快速显示关键指标无需自行聚合。接口能力边界能力说明实时天气温度、湿度、风、能见度、云量、AQI、PM2.5分钟级降水未来 2 小时逐分钟降水概率需调用 minutely 类型小时预报最长 360 小时15 天默认 24 小时天预报最长 15 天默认 5 天含日出日落、温度极值、生活指数气象预警自动提取颜色蓝/黄/橙/红和严重级别一般/较重/严重/特别严重综合数据使用 typeweather 一次返回实时分钟级小时天预警QPS 限制10 次/秒。超出会返回 429 或限流。请求参数与鉴权基础地址GET https://v1.apizero.cn/api/weatherQuery 参数参数名类型必填说明typestring否查询类型realtime、minutely、hourly、daily、weather默认 weather 综合citystring否城市/地区名称如“北京”“朝阳区”。与 location 二选一locationstring否经纬度坐标格式经度,纬度如116.3975,39.9085优先级高于 cityalertstring否是否包含预警true/false默认true仅 realtime/weather 生效daysnumber否天预报步长1~15默认 5仅 daily/weather 生效hoursnumber否小时预报步长1~360默认 24仅 hourly/weather 生效注意city 和 location 至少传一个若都传则以 location 为准。鉴权 Header通过 HTTP 请求头X-API-Key传递 API Key。不传则走匿名额度但有并发与频次限制。建议正式接入时携带 Key。X-API-Key: YOUR_API_KEYcurl 请求示例以下示例请求北京的综合天气数据含预警使用环境变量$APIZERO_API_KEY存放 Keycurl -sS \ -X GET \ -H X-API-Key: $APIZERO_API_KEY \ https://v1.apizero.cn/api/weather?city%E5%8C%97%E4%BA%ACtypeweatheralerttruedays3hours48若不带 API Key可直接去掉 Header 行curl -sS https://v1.apizero.cn/api/weather?city上海typerealtime建议将 URL 中的中文进行 URL 编码如“北京”编码为%E5%8C%97%E4%BA%AC或使用--data-urlencode构造避免部分终端乱码。返回值结构解读响应为 JSON 数组默认第一个元素为成功返回status: 200。核心数据位于data对象中结构如下{ code: 0, msg: 成功, request_id: mota..., data: { type: weather, server_time: 2026-05-06 08:43:01, location: { city: 北京, latitude: 39.9042, longitude: 116.4074, timezone: Asia/Shanghai }, summary: { ... }, realtime: { ... }, minutely: { ... }, hourly: [ ... ], daily: [ ... ], alerts: [ ... ], forecast_keypoint: 未来两小时不会下雨放心出门 } }顶层 summary 字段此字段为 API 自动聚合的“一眼看懂”摘要直接可展示子字段含义temperature实时温度℃apparent_temperature体感温度℃humidity_percent相对湿度%cloudrate_percent云量%skycon天气现象中文如“小雨”skycon_code原始英文 codeskycon_emoji对应 emojivisibility_km能见度kmair_quality包含 aqi、level、level_color、pm25wind含 direction_deg、direction_text16方位、speed_ms、level、level_textalert_count当前生效预警数量实时天气realtime当 type 为realtime或weather时返回。字段与原始彩云 v2.6 一致包括temperature、apparent_temperature、humidity、cloudrate、visibility、winddirection/speedair_qualityaqi、pm25、pm10、o3、no2、so2、co、levelprecipitationnearest 最近的降水点life_index紫外线、舒适度、洗车指数等分钟级降水minutely未来 2 小时逐分钟降水概率格式为数组每 1 分钟一个值mm/h。包含description字段文字总结。小时预报hourly数组按时间升序排列。每个元素包含datetime、temperature、humidity、wind、precipitation、skycon、cloudrate等。天预报daily数组包含date、temperature_max、temperature_min、sunrise、sunset、skycon、life_index具体指数如运动、穿衣、紫外线等。气象预警alerts数组每条预警包含title原始标题如“东城区气象台发布大风蓝色预警[IV/一般]”color提取的颜色蓝色/黄色/橙色/红色level严重级别一般/较重/严重/特别严重description详细描述pub_time发布时间status状态预警中/解除province、city、county行政区划forecast_keypoint一段自然语言描述的预测要点适合直接展示给用户。常见错误与排查HTTP 状态码codemsg原因与处理方法200-1参数错误检查 city/location 是否为空或 type 值是否合法仅支持上述 5 种2001001未知城市城市名称不在内置表且 Open-Meteo 也无法解析请改用 location 参数4011002Key 无效检查 X-API-Key 是否正确复制是否过期4291003请求过于频繁超过 QPS 10/s需增加间隔或使用限流策略5009999服务异常服务端临时故障可稍后重试注意API 在正常返回时 status 为 200业务错误通过 code 和 msg 标识不要仅靠 HTTP 状态码判断。工程化注意事项1. 缓存策略天气数据实时性要求不同建议对实时数据设置 5~10 分钟缓存预报数据可缓存 1 小时。预警数据可跟随实时请求更新。2. 降级方案当 API 返回异常或限流时应展示上次正常返回的缓存数据并提示“数据可能延迟”。3. 城市名称标准化传入 city 时尽量使用标准名称如“北京市”而非“北京首都”。若查询结果中 location.city 与预期不符可考虑改用经纬度。4. 预警颜色处理前端可将color映射为对应 UI 色块蓝 #1E90FF、黄 #FFD700、橙 #FF8C00、红 #FF4500。level用于判断预警的紧急优先展示。5. 安全提醒API Key 不应硬编码在客户端代码如前端 JavaScript中应通过后端代理转发。匿名额度仅供测试生产环境务必携带有效 Key。参考文档彩云天气 API 文档原始 Markdown 文档