彩云天气怎么用：实时、分钟降水和15天预报

商城里的 彩云天气 不是五条不同的接口。地址只有一条：

GET https://v1.apizero.cn/api/weather

五个功能靠 type 换数据包。完整字段和北京示例在该页「接口文档」，以及 原始文档。先在网页上看一眼，再用 天气查询 或 接口调试 打一次，再接到自己的后端。

密钥在 API Key 建。头写成 Authorization: Bearer 你的密钥。不要把 Key 写进页面或安装包。

先发出去

city 和 location 必须有一个。location 是「经度,纬度」，有它时城市名作废。常见城市名能解析；解析失败就换更具体的名字，或直接传坐标。

export APIZERO_API_KEY="你的密钥"

curl -sS -H "Authorization: Bearer $APIZERO_API_KEY" \
  "https://v1.apizero.cn/api/weather?type=weather&city=北京&days=7&hours=48&alert=true"

也认 X-API-Key。匿名可以不带头，走更低的每日次数。成功时 code 为 0，正文在 data。

五个 type：

• weather：综合包（默认）。一次拿实时 + 分钟降水 + 小时 + 天 + 预警。先用这个。
• realtime：只要此刻
• minutely：未来约 2 小时会不会下雨
• hourly：按小时排行程，最长 360 小时（15 天）
• daily：按天看日历，最长 15 天

days 只对综合包和天预报有用，范围 1–15。不传时走接口默认（当前实现是 5 天）；文档示例常写 7。要几天自己传。hours 只对综合包和小时预报有用，范围 1–360，不传是 24。alert 只对综合包和实时有效，默认 true。

type 写错会直接校验失败，合法值就是上面五个。两个定位参数都空，也会失败。

综合包：先读这三处

type=weather 时，页面上能用的多半已经整理好了：

1. data.forecast_keypoint：一句话，例如「多云，今天晚间转小雨」。做标题、推送、语音播报用这一句。
2. data.summary：中文摘要。温度已是摄氏度，湿度、云量是百分比，风向和风力有中文，AQI 带等级和颜色。卡片优先读这里，不要先拆原始字段。
3. data.alerts：气象预警列表。没有预警就是空数组，summary.alert_count 为 0。

data.location 带回解析后的城市、经纬度和时区。data.server_time 是服务端时间。后面的 realtime / minutely / hourly / daily 是完整序列，画图、列表再读它们。

summary 里这些键可以直接上屏：

• skycon / skycon_emoji / skycon_code：天气现象、emoji、英文码
• temperature / apparent_temperature：气温、体感，单位 ℃
• humidity_percent / cloudrate_percent / visibility_km
• wind.speed_ms、wind.direction_text、wind.level、wind.level_text（蒲福 0–12，例如「和风」）
• air_quality.aqi、level、level_color、pm25。颜色：优 green，良 yellow，轻度 orange，中度 red，重度 purple，严重 maroon

原始 realtime 里湿度、云量是 0–1，气压是帕，风速是米/秒。自己算百分比时乘 100。空气质量同时给国标 chn 和美标 usa，国内产品用 chn。

实时：现在的温度、风、空气、舒适度

type=realtime。回包没有分钟/小时/天序列，有 summary、realtime，以及（alert=true 时）alerts。

realtime 比摘要多这些：

• 天气码 skycon，短波辐射 dswrf
• precipitation.local.intensity：本地此刻降水强度；datasource 常见为 radar
• precipitation.nearest.distance / intensity：附近雨区有多远（公里）。远处有雨、本地为 0，卡片可以写「附近有雨」
• 污染物：pm25、pm10、o3、so2、no2、co
• life_index.ultraviolet：紫外线指数和「无 / 弱」这类描述
• life_index.comfort：舒适度，例如「闷热」

适合首页天气条、穿衣提醒。要预报别用这个 type。

skycon 英文码要自己画图标时对照：

• 晴：CLEAR_DAY / CLEAR_NIGHT
• 多云：PARTLY_CLOUDY_DAY / PARTLY_CLOUDY_NIGHT
• 阴：CLOUDY
• 雨：LIGHT_RAIN / MODERATE_RAIN / HEAVY_RAIN / STORM_RAIN / THUNDER_SHOWER
• 雪：LIGHT_SNOW / MODERATE_SNOW / HEAVY_SNOW / STORM_SNOW / SLEET
• 霾与能见度：LIGHT_HAZE / MODERATE_HAZE / HEAVY_HAZE / FOG / DUST / SAND
• 其它：WIND、HAIL

综合包的 summary.skycon 已经是中文，多数页面不必自己翻译。

分钟降水：出门前两小时

type=minutely。看 data.minutely：

• description：现成句子，例如「未来两小时不会有雨」
• precipitation：约 60 个点，未来 1 小时每分钟强度
• precipitation_2h：约 120 个点，未来 2 小时
• probability：短时降水概率分段
• accumulation：累计
• datasource：数据来源，常见 radar

forecast_keypoint 在这个 type 里往往就是短时降水那句。做「还有 X 分钟下雨」读数组；只做文案读 description。

小时预报：按点排行程

type=hourly，用 hours 控制长度，最长 360。

hourly.description 是整段话。序列按小时对齐，每项带 datetime（含时区，例如 2026-07-31T04:00+08:00）：

• temperature / apparent_temperature
• precipitation：value 是强度，probability 是概率
• wind：speed、direction
• humidity、cloudrate、skycon、pressure、visibility、dswrf
• air_quality.aqi、air_quality.pm25（AQI 里仍有 chn / usa）

折线图用温度和降水；列表用 skycon + 温度。综合包里也有同一份 hourly，只是旁边还带着实时和天预报。

天预报：日出日落和生活指数

type=daily，用 days 控制 1–15 天。

每天不只一个天气码：

• skycon：全天
• skycon_08h_20h：白天（约 8 点到 20 点）
• skycon_20h_32h：夜间（约 20 点到次日 8 点）

温度、降水、风也按这三段给 max / min / avg。日历卡片：白天天气 + 最高温 / 最低温。降水带 probability。

另外三组：

• astro：sunrise.time / sunset.time，例如 05:11、19:29
• air_quality：当天 AQI、PM2.5 的最高、平均、最低
• life_index：ultraviolet（紫外线）、carWashing（洗车）、dressing（穿衣）。实时包里的舒适度在这里没有，穿衣指数在这里

湿度、云量、气压、能见度、短波辐射按天也有最大最小平均，图表用得上，普通卡片可以不展示。

气象预警

综合包和实时默认带 alerts。不想要就 alert=false。

每条大致有：

• title：例如「某地气象台发布大风蓝色预警[IV/一般]」
• description：正文
• color：蓝 / 黄 / 橙 / 红
• level：一般 / 较重 / 严重 / 特别严重
• status：预警中、解除等
• province / city / county
• pub_time、source、alert_id

有预警先展示 title 和 color，点开再给 description。全国预警列表是另一条产品，不要和本接口混用。

接到自己的网站

浏览器只打你的后端。服务器再带 Key 去 v1.apizero.cn。

const url = new URL("https://v1.apizero.cn/api/weather");
url.searchParams.set("type", "weather");
url.searchParams.set("city", city);
url.searchParams.set("days", "7");
url.searchParams.set("hours", "48");
url.searchParams.set("alert", "true");

const res = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.APIZERO_API_KEY}` },
});
const json = await res.json();
if (json.code !== 0) throw new Error(json.msg || "weather failed");

const { summary, forecast_keypoint, alerts, hourly, daily, minutely } = json.data;

页面展示 summary + forecast_keypoint；折线用 hourly；日历用 daily；出门前提示用 minutely.description；横幅用 alerts。

只刷新当前温度就 type=realtime。只判断两小时内会不会下雨就 minutely。综合包一次计一次额度，字段最多；能拆开就拆，避免每次把 15 天序列都拉回来。

App、小程序同样把请求放在你的服务端。定位到了经纬度，优先传 location，比城市名准。

回包较长时，用 JSON 工具 的 JSONPath 抽 data.summary、data.hourly.temperature，再抄回项目。

额度

这条按次计，不是大模型那种按 token。具体每日次数和 QPS 看商城页「访问限制」，以当时页上的为准。写这篇时，登录免费档是每日 2,000 次、QPS 3；不带头更低；会员档更高。免费次数用完再看套餐或计费说明，不要换一把空 Key 碰运气。

同一地点短时间重复查，网关可能走几分钟缓存，数字会慢半拍。做「现在有没有雨」可以接受；做秒级雷达动画，这条接口不合适。

常见卡住

• city 与 location 至少传一个：两个都空了
• 无法解析城市：名字太泛或库里没有。改成「北京市朝阳区」，或传 116.3975,39.9085
• location 格式错误：必须是 经度,纬度，经度在前，不要反，不要空格乱进
• type 不合法：只能是 weather / realtime / minutely / hourly / daily
• 401 / missing_token：要走登录额度却没带 Bearer
• 次数用完：看该接口今日已用，不要换 Key
• 浏览器 Failed to fetch：页面直连了网关。改成打你自己的后端，或用接口调试代发

字段对过、额度还在，再接到网站。换城市只改 city 或 location，地址不用换。