天气预报 API

实时天气与未来 7 天预报，默认 Open-Meteo，配置和风天气 Key 后自动切换

数据来源：Open-Meteo / 和风天气

返回统一的 JSON 格式 { code, message, cached, stale, updatedAt, data }，支持跨域，免注册每天可免费调用 100 次，注册后每天 10000 次。

查询实时天气与 7 天预报

GET /api/weather

请求参数

  • city：城市名（city / id / lat+lon 三选一）。重名时取地理编码的第一个结果，其他候选见返回的 candidates，示例 上海
  • id：城市编号（city / id / lat+lon 三选一），取自 /api/weather/city 的 items[].id：配置和风天气时为和风 LocationID，否则为 Open-Meteo（GeoNames）编号。编号只在对应数据源有效，服务端切换数据源后需重新搜索，示例 1816670
  • lat：纬度，-90~90（与 lon 同时提供），示例 31.23
  • lon：经度，-180~180（与 lat 同时提供），示例 121.47

返回字段

  • provider（string）：实际使用的数据源：open-meteo（默认）或 qweather（服务端配置了和风天气 Key 时）。两者输出结构相同，个别字段只有其中一方有值，见各字段说明
  • location（object）：查询地点
  • location.id（string）：城市编号，可作为下次请求的 id 参数：qweather 为和风天气 LocationID（如 101010100），open-meteo 为 GeoNames 编号（如 1816670）。按城市名或 id 查询时有；按经纬度查询时没有此字段
  • location.name（string）：地点名称（如 北京市）；按经纬度查询时为 "纬度,经度" 形式的字符串（保留 2 位小数）
  • location.admin（string）：上级行政区，空格分隔、已去重（如 "北京市 北京"）；按经纬度查询或上游未提供时为空字符串
  • location.country（string|null）：国家名称（如 中国）；按经纬度查询时为 null
  • location.lat（number）：纬度（十进制度，北纬为正）。按城市查询时为地理编码得到的城市坐标，按经纬度查询时为传入值四舍五入到 2 位小数（约 1 公里精度）
  • location.lon（number）：经度（十进制度，东经为正）
  • location.timezone（string|null）：地点所在时区（IANA 名称，如 Asia/Shanghai），current.time 与 daily 的日期、日出日落都按该时区。open-meteo 总有值；qweather 按经纬度查询时为 null
  • current（object）：实时天气
  • current.time（string）：观测/数据时间，当地时间。open-meteo 为 YYYY-MM-DDTHH:mm，不带时区偏移（时区见 location.timezone）；qweather 为带偏移的 YYYY-MM-DDTHH:mm+08:00
  • current.temp（number|null）：气温，单位 ℃
  • current.feelsLike（number|null）：体感温度，单位 ℃
  • current.humidity（number|null）：相对湿度，单位 %（0–100）
  • current.weather（string）：天气现象中文描述（如 多云、小雨）。open-meteo 由 WMO 代码换算，遇到未收录的代码为"未知"；qweather 为上游原文
  • current.code（string|null）：天气代码（字符串，上游缺失时为 null）。open-meteo 为 WMO 代码：0 晴、1 晴间多云、2 多云、3 阴、45 雾、48 雾凇、51 小毛毛雨、53 毛毛雨、55 大毛毛雨、56 冻毛毛雨、57 强冻毛毛雨、61 小雨、63 中雨、65 大雨、66 冻雨、67 强冻雨、71 小雪、73 中雪、75 大雪、77 雪粒、80 小阵雨、81 阵雨、82 强阵雨、85 阵雪、86 强阵雪、95 雷阵雨、96 雷阵雨伴有冰雹、99 强雷阵雨伴有冰雹。qweather 为和风天气图标代码：1xx 晴/云（100 晴、101 多云、102 少云、103 晴间多云、104 阴，150–153 为对应的夜间图标），3xx 雨，4xx 雪，5xx 雾/霾/沙尘，900 热、901 冷、999 未知
  • current.isDay（boolean|null）：仅 open-meteo 有值：true 为白天、false 为夜间（按当地日出日落）；qweather 恒为 null
  • current.windDir（string|null）：风向（风的来向）。open-meteo 由风向角换算为 8 个方位之一：北风、东北风、东风、东南风、南风、西南风、西风、西北风，缺少数据时为 null；qweather 为上游原文（如 西南风，也可能是"无持续风向""旋转风"）
  • current.windScale（string|null）：风力等级（蒲福风级），字符串。open-meteo 由风速换算为 "0"–"12"，缺少数据时为 null；qweather 为上游原值（如 "2"）
  • current.windSpeed（number|null）：风速，单位 km/h（公里/小时，两种数据源相同）
  • current.precip（number|null）：降水量，单位 mm。open-meteo 为最近一个数据间隔（通常 15 分钟）的累计值；qweather 为过去 1 小时的累计值
  • current.pressure（number|null）：气压，单位 hPa（百帕）。open-meteo 为海平面气压；qweather 为上游大气压。上游缺失时为 null
  • daily（array）：未来 7 天逐日预报（第一项为今天，按日期升序）
  • daily[].date（string）：日期，YYYY-MM-DD（当地日期）
  • daily[].weather（string）：当天天气中文描述。open-meteo 为当天最严重的天气现象，由 WMO 代码换算；qweather 为白天天气
  • daily[].weatherNight（string|null）：仅 qweather 有值：夜间天气中文描述；open-meteo 恒为 null
  • daily[].code（string|null）：天气代码，含义同 current.code，上游缺失时为 null。open-meteo 为当天的 WMO 代码；qweather 为白天天气图标代码
  • daily[].tempMax（number|null）：最高气温，单位 ℃
  • daily[].tempMin（number|null）：最低气温，单位 ℃
  • daily[].precip（number|null）：当天总降水量，单位 mm；上游缺失时为 null

搜索城市，获取可用于天气查询的城市编号

GET /api/weather/city

请求参数

  • q（必填）：城市/地区名称关键字，1~30 字（和风天气支持拼音、区县名），示例 汝阳
  • limit：返回候选数量，1~20，示例 10

返回字段

  • provider（string）：搜索使用的数据源，也是 items[].id 所属的服务：qweather（服务端配置了和风天气 Key，id 为和风 LocationID）或 open-meteo（默认，id 为 GeoNames 编号）。id 只能在同一数据源下传给 /api/weather
  • query（string）：实际搜索的关键字（已去除首尾空白）
  • count（number）：返回的候选数量；没有匹配时为 0
  • items（array）：候选地点，按上游相关度排序（第一项即 /api/weather?city= 采用的结果）
  • items[].id（string）：城市编号，传给 /api/weather 的 id 参数可精确查询：qweather 为 LocationID（如 101180309），open-meteo 为 GeoNames 编号（如 1786640）
  • items[].name（string）：地点名称
  • items[].adm1（string|null）：一级行政区（省/直辖市/州，如 河南省）；上游未提供时为 null
  • items[].adm2（string|null）：二级行政区（地级市，如 洛阳）；上游未提供时为 null
  • items[].adm3（string|null）：仅 open-meteo 可能有值：三级行政区（区县）；qweather 恒为 null（区县级地点本身就是 name）
  • items[].country（string|null）：国家名称（如 中国）；上游未提供时为 null
  • items[].countryCode（string|null）：仅 open-meteo 有值：ISO 3166-1 二位国家代码（如 CN）；qweather 恒为 null
  • items[].lat（number|null）：纬度（十进制度，北纬为正）
  • items[].lon（number|null）：经度（十进制度，东经为正）
  • items[].timezone（string|null）：时区（IANA 名称，如 Asia/Shanghai）；上游未提供时为 null
  • items[].type（string|null）：地点类型。qweather 为上游 type（如 city）；open-meteo 为 GeoNames 要素代码（如 PPLA 省会、PPLA2 地级市驻地、PPLA3 区县驻地、PPL 居民点、ADM3 区县级行政区）
  • items[].population（number|null）：仅 open-meteo 可能有值：人口数；qweather 或上游未提供时为 null