彩云天气weather
基于彩云天气 v2.6 的全功能天气接口，覆盖： • 实时天气（温度/湿度/风/能见度/AQI/PM2.5） • 分钟级降水预报（未来 2 小时） • 小时预报（最长 360 小时 = 15 天） • 天预报（最长 15 天，含日出日落、温度极值、生活指数） • 综合数据（一次返回全部 + 气象预警） 特色： • 支持城市名直接查询（内置 ~140 个常用中国城市表 + Open-Meteo 兜底，无需高德/百度 Key） • 自动中文化：skycon 转中文、风向转 16 方位、风速转蒲福风级、AQI 转等级颜色 • 预警标准化：从原始 title 提取颜色（蓝/黄/橙/红）和级别（一般/较重/严重/特别严重） • 顶层 summary 字段提供"一眼看懂"的实时摘要
1. 基本信息
| 接口地址 | https://v1.apizero.cn/api/weather |
|---|---|
| 请求方法 | GET |
| 分类 | life |
| 提供方 | 极数本源 |
| 计费模式 | 免费试用 |
| 单次消耗 | 0 积分 |
| 起步价 | — |
| QPS 限制 | 10 req/s |
| 每日免费额度 | 2000 次（已认证用户） |
| 匿名每日额度 | 100 次（无 API Key） |
| VIP 免费 | 否 |
| 调用次数 |
2. 认证
匿名可调用：QPS=2、日 100 次；登录后：QPS=10、日 2000 次。
获取 API Key：登录 https://apizero.cn/account/keys
3. 请求参数
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
type | string | 否 | 查询类型：realtime / minutely / hourly / daily / weather（默认 weather 综合） | — |
city | string | 否 | 城市/地区名称（如「北京」「朝阳区」），与 location 二选一 | — |
location | string | 否 | 经纬度坐标，格式 经度,纬度（如 116.3975,39.9085），优先级高于 city | — |
alert | string | 否 | 是否包含气象预警，true/false，默认 true（仅 realtime/weather 生效） | — |
days | integer | 否 | 天预报步长，1~15，默认 5（仅 daily/weather 生效） | — |
hours | integer | 否 | 小时预报步长，1~360，默认 24（仅 hourly/weather 生效） | — |
4. 请求头
| Header | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
X-API-Key | string | 否 | API Key（不传走匿名额度） | — |
5. 请求示例 (cURL)
curl "https://v1.apizero.cn/api/weather?type=%3Ctype%3E&city=%3Ccity%3E&location=%3Clocation%3E&alert=%3Calert%3E&days=%3Cdays%3E&hours=%3Chours%3E&key=YOUR_API_KEY"6. 响应字段
| 字段 | 类型 | 说明 | 示例 |
|---|---|---|---|
type | string | 回显的查询类型 | — |
location.city | string | 解析后的城市名（如传 city 参数） | — |
location.longitude | number | 经度 | — |
location.latitude | number | 纬度 | — |
location.timezone | string | 时区（如 Asia/Shanghai） | — |
server_time | string | 上游数据时间戳（YYYY-MM-DD HH:mm:ss） | — |
forecast_keypoint | string | 彩云天气一句话总结金句（如「未来两小时不会下雨，放心出门」） | — |
summary | object | ★ 实时摘要（一眼看懂当前天气状态） | — |
summary.skycon | string | 天气现象中文（晴/多云/小雨/...） | — |
summary.skycon_emoji | string | 天气现象 emoji（☀️/⛅/🌧️/...） | — |
summary.skycon_code | string | 天气现象英文枚举（CLEAR_DAY/LIGHT_RAIN/...，详见枚举表） | — |
summary.temperature | number | 温度 ℃ | — |
summary.apparent_temperature | number | 体感温度 ℃ | — |
summary.humidity_percent | number | 相对湿度 %（0~100） | — |
summary.cloudrate_percent | number | 云量 %（0~100） | — |
summary.visibility_km | number | 能见度 km | — |
summary.wind.speed_ms | number | 风速 m/s | — |
summary.wind.direction_deg | number | 风向角度（0~360°，0°=正北顺时针） | — |
summary.wind.direction_text | string | 风向中文（北风/东北风/...，16 方位） | — |
summary.wind.level | number | 蒲福风级（0~12） | — |
summary.wind.level_text | string | 风级中文（无风/软风/...飓风） | — |
summary.air_quality.aqi | number | 空气质量指数（中国标准） | — |
summary.air_quality.level | string | AQI 等级中文（优/良/轻度污染/...） | — |
summary.air_quality.level_color | string | AQI 颜色（green/yellow/orange/red/purple/maroon） | — |
summary.air_quality.pm25 | number | PM2.5 浓度 μg/m³ | — |
summary.alert_count | number | 当前生效的气象预警数量 | — |
alerts | array | 气象预警列表（无预警时为空数组） | — |
alerts[].title | string | 预警标题（含级别） | — |
alerts[].description | string | 预警内容详情 | — |
alerts[].color | string | 预警颜色：蓝色/黄色/橙色/红色 | — |
alerts[].level | string | 预警级别：一般/较重/严重/特别严重 | — |
alerts[].status | string | 状态（预警中/解除等） | — |
alerts[].province | string | 省份 | — |
alerts[].city | string | 城市 | — |
alerts[].county | string | 区/县 | — |
alerts[].pub_time | string | 发布时间 | — |
alerts[].source | string | 数据来源（如「国家预警信息发布中心」） | — |
realtime | object | 实时天气详情（type=realtime/weather 时有） | — |
realtime.temperature | number | 温度 ℃ | — |
realtime.apparent_temperature | number | 体感温度 ℃ | — |
realtime.humidity | number | 湿度（0~1，乘 100 即百分比） | — |
realtime.cloudrate | number | 云量（0~1） | — |
realtime.skycon | string | 天气现象英文枚举 | — |
realtime.visibility | number | 能见度 km | — |
realtime.dswrf | number | 向下短波辐射通量（W/m²） | — |
realtime.pressure | number | 气压 Pa（除以 100 为 hPa） | — |
realtime.wind.speed | number | 风速 m/s | — |
realtime.wind.direction | number | 风向 0~360° | — |
realtime.precipitation | object | 降水信息（local 当前位置 / nearest 最近降水点） | — |
realtime.air_quality | object | 空气质量（pm25/pm10/o3/so2/no2/co/aqi/description） | — |
realtime.life_index | object | 生活指数（紫外线/舒适度/穿衣/感冒/洗车） | — |
minutely.precipitation_2h | number[] | 未来 2 小时分钟级降水强度（120 个值） | — |
minutely.description | string | 未来 2 小时降水文字描述 | — |
hourly.skycon[] | object[] | 逐小时天气现象（{datetime, value: skycon 枚举}） | — |
hourly.temperature[] | object[] | 逐小时温度 | — |
hourly.precipitation[] | object[] | 逐小时降水量 | — |
hourly.wind[] | object[] | 逐小时风速风向 | — |
hourly.humidity[] | object[] | 逐小时湿度 | — |
hourly.cloudrate[] | object[] | 逐小时云量 | — |
hourly.air_quality.aqi[] | object[] | 逐小时 AQI | — |
daily.astro[] | object[] | 逐日日出日落 {date, sunrise, sunset} | — |
daily.skycon[] | object[] | 逐日全天天气 | — |
daily.skycon_08h_20h[] | object[] | 逐日白天天气 | — |
daily.skycon_20h_32h[] | object[] | 逐日夜间天气 | — |
daily.temperature[] | object[] | 逐日温度（含 max/min/avg） | — |
daily.life_index | object | 生活指数（紫外线/洗车/穿衣/舒适/感冒） | — |
7. 响应示例
{
"code": 0,
"msg": "成功",
"data": {
"type": "weather",
"location": {
"city": "北京",
"longitude": 116.4074,
"latitude": 39.9042,
"timezone": "Asia/Shanghai"
},
"server_time": "2026-05-06 08:43:01",
"forecast_keypoint": "未来两小时不会下雨，放心出门",
"summary": {
"skycon": "小雨",
"skycon_emoji": "🌦️",
"skycon_code": "LIGHT_RAIN",
"temperature": 21.5,
"apparent_temperature": 21.8,
"humidity_percent": 55,
"cloudrate_percent": 100,
"visibility_km": 20.3,
"wind": {
"speed_ms": 3.7,
"direction_deg": 239.9,
"direction_text": "西南偏南风",
"level": 3,
"level_text": "微风"
},
"air_quality": {
"aqi": 68,
"level": "良",
"level_color": "yellow",
"pm25": 27
},
"alert_count": 1
},
"alerts": [
{
"title": "东城区气象台发布大风蓝色预警[IV/一般]",
"description": "预计 6 日早晨至午后...有 3-4 级偏北风，阵风 6-7 级...",
"color": "蓝色",
"level": "一般",
"status": "预警中",
"province": "北京市",
"city": "北京城区",
"county": "东城区",
"pub_time": "2026-05-05 16:46:00",
"source": "国家预警信息发布中心",
"alert_id": "11010141600000_..."
}
],
"realtime": "...（彩云原始 realtime 字段，详见上方字段说明）",
"minutely": "...（type=weather 才有）",
"hourly": "...（type=weather 才有）",
"daily": "...（type=weather 才有）"
},
"request_id": "mota..."
}8. 错误码
| code | status | 说明 |
|---|---|---|
0 | OK | 成功 |
4000 | Bad Request | 参数错误：type 不合法 / city+location 都未传 / 经纬度格式错 / 城市无法解析 |
4011 | Unauthorized | API Key 无效 |
4013 | Forbidden | API Key 已暂停 |
4014 | Forbidden | 当前 IP 不在 API Key 白名单内 |
4022 | Payment Required | 余额不足 |
4029 | Too Many Requests | QPS 限流 |
4030 | Too Many Requests | 今日免费额度已用完 |
5020 | Bad Gateway | 上游不可用：彩云回源失败 / 数据格式异常 |
5021 | Bad Gateway | 上游响应非 JSON |
5030 | Service Unavailable | 上游凭据未配置（运维问题） |
9. 变更日志
- 1.0.0(2026-05-06)
- 首次发布：5 种 type（realtime/minutely/hourly/daily/weather）+ 城市名直查
- 内置 ~140 个常用城市经纬度表 + Open-Meteo Geocoding 兜底（不依赖高德/百度 Key）
- 顶层 summary 实时摘要：skycon 中文化、风向 16 方位、风级蒲福分级、AQI 等级颜色
- 预警 alerts 标准化：自动提取颜色（蓝/黄/橙/红）和级别（一般/较重/严重/特别严重）