免费气象数据中台 API

气象数据中台 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"))

接入建议

  1. 缓存城市列表：/api/weatherArea/list 数据相对稳定，建议本地缓存，按省市区检索后再请求实况 / 预报。

  2. 按 ID 查询：务必使用列表返回的 id，不要传无效 ID（会返回 [D1002] 记录不存在）。

  3. 区分实况与预报：首页展示用 weatherLive；未来几天用 weatherForecast；中长期趋势用 weatherForecast40。

  4. 注意字段差异：多日预报拆分白天 / 夜间；40 天预报提供 maxTemperature / minTemperature 与综合 weather 文案。

  5. 错误处理：先判断 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）及实测接口响应整理，示例数据以请求时刻为准。

posted @ 2026-08-19 16:31  醉代码  阅读(69)  评论(0)    收藏  举报