气象数据中台 API

一句话介绍 ：面向开发者的全国气象数据服务，覆盖 34 个省级行政区、3200+ 区县级站点 ，提供实时实况、多日预报与未来 40 天趋势，JSON 接口即查即用。

在线文档 ：https://api.xzt.me/index.html 服务基址 ：https://api.xzt.me 版本：1.0.0 协议：HTTPS · RESTful · JSON · OpenAPI 3.0

为什么选择气象数据中台？

亮点	说明
全国覆盖	省 / 市 / 区县三级区域编码，当前约 3242 个可查询区域
能力齐全	实况、多日预报、40 天中长期趋势，一套接口搞定
接入简单	标准 HTTP GET + JSON，几分钟即可联调
字段清晰	气温、天气现象、风向风力、湿度、能见度等业务字段齐全
统一响应	全局 `code / type / message / result / time` 结构，便于封装 SDK

适用场景 ：天气 App / 小程序、出行与物流调度、农业与户外作业、活动策划、物联网与智慧城市、内容运营与资讯推送等。

快速开始（3 步）

1. 查区域 ID

复制代码

GET https://api.xzt.me/api/weatherArea/list

从返回列表中拿到目标区域的 id（例如北京：86101020100）。

2. 查实时天气

复制代码

GET https://api.xzt.me/api/weatherLive/detail?Id=86101020100

3. 查预报（多日 / 40 天）

复制代码

GET https://api.xzt.me/api/weatherForecast/detail?Id=86101020100
GET https://api.xzt.me/api/weatherForecast40/detail?Id=86101020100

推荐流程：先拉城市列表缓存区域 ID，再按 ID 查询实况与预报，避免每次按地名模糊匹配。

接口总览

接口	方法	说明
`/api/weatherArea/list`	GET	气象城市 / 区县列表
`/api/weatherLive/detail`	GET	当日气象实况
`/api/weatherForecast/detail`	GET	多日气象预报
`/api/weatherForecast40/detail`	GET	未来 40 天气象预报

认证说明

接口采用 Bearer JWT 鉴权（OpenAPI securitySchemes.Bearer）：

复制代码

Authorization: Bearer <your_token>

联调与正式接入时，请在控制台或管理员处申请 Token，并在请求头中携带。在线调试页： https://api.xzt.me/index.html

统一响应结构

所有接口均返回统一信封结构：

字段	类型	说明
`code`	number	状态码，成功一般为 `200`
`type`	string	`success` / `warning` / `error`
`message`	string	提示或错误信息
`result`	object / array / null	业务数据
`extras`	object / null	附加数据
`time`	string	服务端响应时间

成功示例（结构） ：

复制代码

{
  "code": 200,
  "type": "success",
  "message": "",
  "result": {},
  "extras": null,
  "time": "2026-08-19 15:56:44"
}

失败示例 ：

复制代码

{
  "code": 400,
  "type": "error",
  "message": "[D1002] 记录不存在",
  "result": null,
  "extras": null,
  "time": "2026-08-19 15:56:04"
}

接口详情

1. 气象城市列表

获取全国可查询区域（省 / 市 / 区县）及对应主键 id。

URL ：GET /api/weatherArea/list
参数：无
标签：weatherArea（气象城市服务）

result 数组元素字段

字段	类型	说明
`id`	string / number	区域主键，后续接口必传
`province`	string	省份
`city`	string	城市
`district`	string	区县 / 区域

真实示例（节选） ：

复制代码

{
  "code": 200,
  "type": "success",
  "result": [
    {
      "id": "86101020100",
      "province": "北京",
      "city": "北京",
      "district": "北京"
    },
    {
      "id": "86101020200",
      "province": "北京",
      "city": "北京",
      "district": "海淀"
    },
    {
      "id": "86101020300",
      "province": "北京",
      "city": "北京",
      "district": "朝阳"
    }
  ]
}

覆盖概况（实测）

区域条目：约 3242
省级行政区：约 34 （含港澳台）
省市组合：约 375

2. 当日气象实况

按区域 ID 获取当前天气现象、气温、风向风力、湿度、能见度等。

URL ：GET /api/weatherLive/detail
参数

参数	位置	必填	类型	说明
`Id`	query	是	int64	区域主键，与城市列表 `id` 一致

result 字段

字段	类型	说明
`areaData`	object	区域信息（`id` / `province` / `city` / `district`）
`weather`	string	天气现象，如「多云」
`temperature`	number	实时气温（℃）
`windDirection`	string	风向
`windPower`	string	风力
`humidity`	string	空气湿度
`visibility`	string	能见度
`updateTime`	string	数据更新时间

真实示例（北京） ：

复制代码

{
  "code": 200,
  "type": "success",
  "message": "",
  "result": {
    "areaData": {
      "id": "86101020100",
      "province": "北京",
      "city": "北京",
      "district": "北京"
    },
    "weather": "多云",
    "temperature": 31.1,
    "windDirection": "南风",
    "windPower": "2级",
    "humidity": "58%",
    "visibility": "19km",
    "updateTime": "2026-08-19 14:15:57"
  },
  "extras": null,
  "time": "2026-08-19 15:56:44"
}

3. 多日气象预报

返回未来若干天的白天 / 夜间天气、气温与风力信息，适合首页天气卡片、行程提醒等。

URL ：GET /api/weatherForecast/detail
参数：Id（必填，区域主键）

result 字段

字段	类型	说明
`areaData`	object	区域信息
`forecasts`	array	多日预报列表

forecasts[] 字段

字段	类型	说明
`date`	string	气象日期
`week`	string	星期（如「今天」「星期四」）
`dayWeather`	string	白天天气现象
`nightWeather`	string	夜间天气现象
`dayTemperature`	number	白天气温（℃）
`nightTemperature`	number	夜间气温（℃）
`dayWindDirection`	string	白天风向
`nightWindDirection`	string	夜间风向
`dayWindPower`	string	白天风力
`nightWindPower`	string	夜间风力

真实示例（北京，节选前 2 天） ：

复制代码

{
  "code": 200,
  "type": "success",
  "result": {
    "areaData": {
      "id": "86101020100",
      "province": "北京",
      "city": "北京",
      "district": "北京"
    },
    "forecasts": [
      {
        "date": "2026-08-19 00:00:00",
        "week": "今天",
        "dayWeather": "晴",
        "nightWeather": "多云",
        "dayTemperature": 31,
        "nightTemperature": 23,
        "dayWindDirection": "南风",
        "nightWindDirection": "东南风",
        "dayWindPower": "<3级",
        "nightWindPower": "<3级"
      },
      {
        "date": "2026-08-20 00:00:00",
        "week": "星期四",
        "dayWeather": "雷阵雨",
        "nightWeather": "雷阵雨",
        "dayTemperature": 30,
        "nightTemperature": 23,
        "dayWindDirection": "南风",
        "nightWindDirection": "东风",
        "dayWindPower": "<3级",
        "nightWindPower": "<3级"
      }
    ]
  }
}

4. 未来 40 天气象预报

面向中长期趋势展示：最高 / 最低气温、天气描述，覆盖约 40 天。

URL ：GET /api/weatherForecast40/detail
参数：Id（必填，区域主键）

result 字段

字段	类型	说明
`areaData`	object	区域信息
`forecasts`	array	40 天预报列表

forecasts[] 字段

字段	类型	说明
`date`	string	气象日期
`week`	string	星期
`dayWeather`	string	白天天气现象
`nightWeather`	string	夜间天气现象
`weather`	string	综合天气描述（如「雷阵雨转多云」）
`maxTemperature`	number	最高气温（℃）
`minTemperature`	number	最低气温（℃）

真实示例（北京，节选） ：

复制代码

{
  "code": 200,
  "type": "success",
  "result": {
    "areaData": {
      "id": "86101020100",
      "province": "北京",
      "city": "北京",
      "district": "北京"
    },
    "forecasts": [
      {
        "date": "2026-08-19 00:00:00",
        "week": "星期三",
        "dayWeather": "多云",
        "nightWeather": "多云",
        "weather": "多云",
        "maxTemperature": 31,
        "minTemperature": 23
      },
      {
        "date": "2026-08-20 00:00:00",
        "week": "星期四",
        "dayWeather": "雷阵雨",
        "nightWeather": "雷阵雨",
        "weather": "雷阵雨",
        "maxTemperature": 30,
        "minTemperature": 23
      }
    ]
  }
}

调用示例

cURL

复制代码

# 城市列表
curl -X GET "https://api.xzt.me/api/weatherArea/list" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <your_token>"

# 实况
curl -X GET "https://api.xzt.me/api/weatherLive/detail?Id=86101020100" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <your_token>"

# 多日预报
curl -X GET "https://api.xzt.me/api/weatherForecast/detail?Id=86101020100" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <your_token>"

# 40 天预报
curl -X GET "https://api.xzt.me/api/weatherForecast40/detail?Id=86101020100" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <your_token>"

JavaScript（fetch）

复制代码

const BASE = "https://api.xzt.me";
const token = "<your_token>";

async function getLiveWeather(areaId) {
  const res = await fetch(`${BASE}/api/weatherLive/detail?Id=${areaId}`, {
    headers: {
      Accept: "application/json",
      Authorization: `Bearer ${token}`,
    },
  });
  const data = await res.json();
  if (data.code !== 200) throw new Error(data.message || "请求失败");
  return data.result;
}

// 示例：北京
getLiveWeather("86101020100").then(console.log);

Python（requests）

复制代码

import requests

BASE = "https://api.xzt.me"
HEADERS = {
    "Accept": "application/json",
    "Authorization": "Bearer <your_token>",
}

def get_live(area_id: str):
    r = requests.get(
        f"{BASE}/api/weatherLive/detail",
        params={"Id": area_id},
        headers=HEADERS,
        timeout=10,
    )
    r.raise_for_status()
    data = r.json()
    if data.get("code") != 200:
        raise RuntimeError(data.get("message"))
    return data["result"]

print(get_live("86101020100"))

接入建议

缓存城市列表 ：/api/weatherArea/list 数据相对稳定，建议本地缓存，按省市区检索后再请求实况 / 预报。
按 ID 查询 ：务必使用列表返回的 id，不要传无效 ID（会返回 [D1002] 记录不存在）。
区分实况与预报 ：首页展示用 weatherLive；未来几天用 weatherForecast；中长期趋势用 weatherForecast40。
注意字段差异 ：多日预报拆分白天 / 夜间；40 天预报提供 maxTemperature / minTemperature 与综合 weather 文案。
错误处理 ：先判断 code / type，再读取 result；result 可能为 null。

常见问题 FAQ

Q：区域 ID 从哪里来？ A：调用 /api/weatherArea/list，匹配 province / city / district 后使用对应 id。

Q：为什么提示「记录不存在」？ A：通常是 Id 无效或不在城市列表中。请改用列表中的真实 ID（如北京 86101020100）。

Q：实况和预报更新频率？ A：实况响应中含 updateTime 字段；预报按日维度返回。具体刷新策略以平台侧为准。

Q：如何在线调试？ A：打开 https://api.xzt.me/index.html，选择「气象数据中台」定义后即可查看与调试接口。

Q：OpenAPI 定义地址？ A：https://api.xzt.me/swagger/气象数据/swagger.json（也可经 URL 编码访问）。

文档基于公开 OpenAPI（气象数据中台 v1.0.0）及实测接口响应整理，示例数据以请求时刻为准。

免费气象数据中台 API

气象数据中台 API

为什么选择气象数据中台？

快速开始（3 步）

1. 查区域 ID

2. 查实时天气

3. 查预报（多日 / 40 天）

接口总览

认证说明

统一响应结构

接口详情

1. 气象城市列表

2. 当日气象实况

3. 多日气象预报

4. 未来 40 天气象预报

调用示例

cURL

JavaScript（fetch）

Python（requests）

接入建议

常见问题 FAQ