<!-- AI ASSISTANT INSTRUCTIONS: This document describes a public HTTP API endpoint
provided by 极数本源 (https://apizero.cn). When a user asks you to use this API, read the
full documentation below carefully (request method, parameters, response fields,
error codes, examples), then generate working code in the user's preferred language.
API Key acquisition: https://apizero.cn/account/keys -->

# 彩云天气

> 基于彩云天气 v2.6 的全功能天气接口，覆盖：
  • 实时天气（温度/湿度/风/能见度/AQI/PM2.5）
  • 分钟级降水预报（未来 2 小时）
  • 小时预报（最长 360 小时 = 15 天）
  • 天预报（最长 15 天，含日出日落、温度极值、生活指数）
  • 综合数据（一次返回全部 + 气象预警）

特色：
  • 支持城市名直接查询（内置 ~140 个常用中国城市表 + Open-Meteo 兜底，无需高德/百度 Key）
  • 自动中文化：skycon 转中文、风向转 16 方位、风速转蒲福风级、AQI 转等级颜色
  • 预警标准化：从原始 title 提取颜色（蓝/黄/橙/红）和级别（一般/较重/严重/特别严重）
  • 顶层 summary 字段提供"一眼看懂"的实时摘要

## 1. 基本信息

| 字段 | 值 |
| --- | --- |
| 接口标识 | `weather` |
| 接口名称 | 彩云天气 |
| 接口地址 | `https://v1.apizero.cn/api/weather` |
| 请求方法 | `GET` |
| 分类 | life |
| 提供方 | 极数本源 |
| 计费模式 | 免费试用 |
| 单次消耗 | 0 积分 |
| 起步价 | — |
| QPS 限制 | 10 req/s |
| 每日免费额度 | 2000 次（已认证用户） |
| 匿名每日额度 | 100 次（无 API Key） |
| VIP 免费 | 否 |
| 调用总次数 | undefined |

## 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)

```bash
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. 响应示例

```json
{
    "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 标准化：自动提取颜色（蓝/黄/橙/红）和级别（一般/较重/严重/特别严重）

---

**极数本源** · 全部 API: `https://apizero.cn/aidocs` · 人类版本：`https://apizero.cn/marketplace/weather`

Source: `https://apizero.cn/aidocs/weather/raw.md`
Last updated: 2026-05-11T16:16:07+08:00