数据下载技术文档
>
API技术文档
>
历史数据
>
历史气象数据 API 使用指南
Appearance
历史气象数据 API 使用指南
本文档将引导您完成从申请历史气象数据 API 到生成批量调用链接、导出执行脚本的完整操作流程。
一、页面入口
1.1 申请历史气象数据 API
有两种方式进入「历史气象数据 API 申请」页面：
方式一：数据服务页快捷入口
点击顶部导航栏「数据服务」进入数据服务页面
在页面中部找到「快捷服务入口」区域
点击「历史 API」卡片，即可进入申请页面
方式二：API 市场入口
在「数据服务」页面，找到「气象数据 API 服务」区域
点击顶部的「API 历史」标签页
点击「立即了解」按钮，即可进入申请页面
1.2 查看我的 API
登录后，点击导航栏右侧的「控制台」，默认进入「我的 API」页面
页面默认展示实时 API 列表，点击上方标签切换到「历史预测」
在历史 API 列表中找到已申请的 API，点击「立即使用」即可进入详情页
二、申请历史气象数据 API
进入「历史气象数据 API 申请」页面后，按以下步骤操作：
步骤 1：选择版本
页面顶部展示两种版本供选择：
| 版本 | 适用场景 | 访问量 | QPS | 有效期 |
|---|---|---|---|---|
| 试用版申请 | 适合验证接口、调试参数和联调测试 | 1000 次 | 5 次/秒 | 30 天 |
| 付费版下单 | 适合正式生产、稳定接入和长期使用 | 按需定制 | 按需定制 | 按需定制 |
点击对应卡片即可选中
切换版本后，页面底部的气象要素展示会随之变化（试用版仅支持单个预报天数，付费版支持多选）
申请成功的 API 目前提供自 2025 年 1 月 1 日 起至今的历史数据查询
步骤 2：配置基础参数
2.1 时间分辨率
可选：「1 小时」（常规接入）或「15 分钟」（高频业务）
点击卡片即可选中
2.2 区域范围
目前支持「中国区」
其他区域（如全球范围）将在后续开放，暂不可选
2.3 预报天数
| 天数 | 类型 |
|---|---|
| 10 天 | 短中期 |
| 15 天 | 标准 |
| 30 天 | 延伸 |
| 45 天 | 次季节 |
试用版：只能选择 1 个 预报天数
付费版：支持 多选，可同时申请多个天数组合
点击卡片切换选中状态
2.4 查看可提供的气象要素
选择预报天数后，系统会根据您选择的区域范围、时间分辨率和预报天数，自动加载当前参数组合下可用的气象要素列表：
试用版：所有要素以网格形式一次性展示，显示每项要素的名称、编码和单位
付费版：按预报天数 分组展示，每组可独立展开/收起，并支持「全部展开」「全部收起」快捷操作
要素列表为 只读信息，表示该套餐可调用的要素范围，具体在详情页生成链接时选择
步骤 3：填写申请信息
在页面底部填写用于审核与沟通的信息：
所属行业：从下拉列表选择
单位名称：填写申请单位全称
如果您已登录并完善了个人信息，系统会自动预填这两项内容。
步骤 4：提交申请
页面右侧「申请确认」面板会实时汇总您的所有配置，确认无误后点击提交按钮：
试用版：点击「提交试用版申请」
付费版：点击「提交付费版订单」
提交结果
| 版本 | 审核方式 | 后续操作 |
|---|---|---|
| 试用版 | 自动审核通过 | 弹窗提示申请成功，可点击「查看我的 API」跳转至历史 API 列表页 |
| 付费版 | 等待人工审核 | 弹窗提示提交成功，可选择跳转至「我的订单」页面查看审核进度 |
三、生成 API 调用链接
API 申请通过后，在「控制台」→「我的 API」→「历史 预测」中点击「立即使用」进入详情页。
详情页是您配置调用参数、批量生成链接、导出执行代码的核心页面。
步骤 1：配置调用参数
1.1 设置位置坐标
有两种方式设置坐标：
城市选择（推荐）：在「城市选择」下拉框搜索并选择目标城市，系统自动填充经度和纬度
手动输入：直接在经度、纬度输入框中填写数值
坐标有效范围限制在中国区域，会在输入框旁显示提示：
| 参数 | 默认范围 |
|---|---|
| 经度 | 73.5 ~ 135.5 |
| 纬度 | 3.5 ~ 53.6 |
1.2 设置查询天数
在「查询天数」输入框中填写需要查询的天数
页面会提示当前套餐上限（例如：「输入不能超过 15 天」）
输入值必须为正整数
1.3 选择日期范围
使用「开始日期」和「结束日期」选择查询的时间区间
可选日期范围由系统数据情况自动限制：
最早日期：历史数据最早起报日
最晚日期：最新可用起报日
页面会显示当前的历史 API 数据范围（例如：「自 2025 年 1 月 1 日 起至 今日」）
结束日期不能早于开始日期
1.4 选择起报时次
「起报时次」支持 多选，可同时选择多个时次
可选时次根据您的套餐配置自动加载，常见值为「08 时」和「20 时」
至少需要选择 1 个 起报时次
1.5 选择 AppKey
从下拉列表选择已创建的 AppKey（用于接口鉴权）
如果尚未创建 AppKey，请先前往「我的 API」页面创建
1.6 重置参数
- 点击「查询重置」按钮可清除城市、坐标、已选要素等，恢复为套餐默认配置
步骤 2：选择气象要素
在「气象要素」区域，按以下方式操作：
搜索要素：在顶部搜索框输入要素名称、编码或单位关键字，列表会实时过滤
勾选要素：点击要素前的复选框即可选中或取消
全选/反选：点击「全选」可一键选中当前过滤后的所有要素；再次点击则取消全选
查看已选：页面下方「已选择要素」区域以标签形式展示所有选中项，每个标签右侧的 `×` 按钮可单独移除
清空已选：点击「清空已选」按钮可一次性移除所有选中
要素个数限制
每个请求最多可选 20 个 气象要素（试用版和付费版当前均为 20 个，后续可能根据套餐单独调整）。选择过程中会有以下提示与行为：
顶部提示条：要素列表上方会显示「每个请求最多可选 20 个气象要素（已选 X / 20）」，当已选数量达到上限时，括号内数字会变为橙色高亮
全选自动截断：如果当前过滤后的要素数量超过剩余可选项，点击「全选」会自动截断到上限数量，并弹出提示
未选中项自动禁用：当已选数量达到上限时，未选中的要素会自动置灰并禁用，已选中的要素仍可点击取消
生成链接兜底校验：点击「生成链接」时系统会再次校验要素数量，超出限制时提示并阻止生成
页面会实时显示要素总数、当前搜索结果数量以及已选进度（例如：「当前显示 23 / 48 个要素，可按名称或单位搜索。已选 5 / 20 项。」）。
步骤 3：生成链接
确认所有参数配置完成后：
点击「生成链接」按钮
系统会按「日期范围 × 起报时次」为每一天的每个时次生成一条独立的 API 调用链接
例如：查询日期为 7 天，起报时次选择 08 时和 20 时，则生成 7 × 2 = 14 条 链接
生成前系统会校验必填参数：坐标有效范围、查询天数、日期范围、起报时次、AppKey、气象要素（至少 1 项）。校验失败会以提示消息告知。
步骤 4：管理生成的链接
4.1 查看与复制
链接以表格形式展示：序号、链接说明（起报时间）、完整 URL、操作
单条复制：点击表格中某条 URL 右侧的「复制」按钮
批量下载：点击右上角「下载链接列表」按钮，将所有 URL 按行导出为
.txt文件
4.2 执行脚本
生成链接后，页面下方「执行代码」面板会自动填充可直接运行的脚本：
支持 Python 和 JavaScript 两种语言，点击标签页切换
脚本功能：遍历链接列表，逐一发送请求并打印返回结果
点击「下载 Python 脚本」或「下载 JavaScript 脚本」按钮可导出
.py/.js文件
Python 脚本依赖：requests
Bash
pip install requests步骤 5：参考 API 文档
详情页底部提供了完整的在线 API 文档，分为三个板块：
5.1 请求参数
以表格形式列出所有 URL 查询参数：
| 参数名 | 说明 | 参数类型 | 默认值 | 必填 |
|---|---|---|---|---|
key | 您的 AppKey | 字符串 | 无 | 是 |
loc | 位置坐标，格式：经度,纬度 | 字符串 | 无 | 是 |
baseTime | 起报时间，格式：yyyyMMddHH | 字符串 | 当前可用起报 | 是 |
fcst_days | 查询天数 | 整数 | 10 | 否 |
fcst_hours | 起报时次 | 整数 | 0 | 否 |
fields | 气象要素列表，用逗号分隔 | 字符串 | 无 | 否 |
t_res | 时间分辨率 | 字符串 | 1h | 否 |
tz | 时区（东八区为 8） | 整数 | 8 | 否 |
subscriptionId | API 访问标识 | 字符串 | 无 | 是 |
timeStart | 返回数据开始时间 | 字符串 | 无 | 否 |
timeEnd | 返回数据结束时间 | 字符串 | 无 | 否 |
5.2 返回参数
接口返回 JSON 结构，主要字段如下：
| 字段名 | 类型 | 说明 |
|---|---|---|
code | 整数 | 业务状态码，200 表示成功 |
message | 字符串 | 返回说明 |
data | 对象 | 响应数据主体 |
data.units | 对象 | 返回字段与单位的映射表 |
data.data | 数组 | 按时间升序排列的逐时/逐分钟数据序列 |
data.data[].time | 字符串 | 数据时间，包含时区信息，如 2026-05-01T09:00+08:00 |
data.time_init | 字符串 | 本次数据的起报时间 |
返回示例：
JSON
{
"code": 200,
"message": "成功",
"data": {
"units": {
"ws50m": "m/s"
},
"data": [
{ "time": "2026-05-01T09:00+08:00", "ws50m": 3.86 },
{ "time": "2026-05-01T09:15+08:00", "ws50m": 4.09 }
],
"time_init": "2026-05-01T08:00+08:00"
}
}5.3 错误码说明
常见错误码及处理方式：
| 错误码 | 类型 | 说明 | 处理建议 |
|---|---|---|---|
| 500 | 系统异常 | 服务器内部错误 | 稍后重试；如持续出现请联系技术支持 |
| 10001 | 服务异常 | 查询失败 | 建议重试，失败后检查参数 |
| 10005 | 额度限制 | 超过访问量上限 | 等待次日刷新或升级套餐 |
| 10006 | 数据时效 | 要素超出有效期 | 调整查询时间范围 |
| 10012 | 鉴权校验 | 非法 AppKey | 确认 AppKey 是否正确、启用 |
| 20001 | 参数校验 | 缺失必选参数 | 检查 key、loc、baseTime 等是否传入 |
| 20003 | 要素订阅 | 要素未订阅 | 在控制台确认套餐包含该要素 |
| 20007 | 坐标校验 | 经度超范围 | 检查经度是否在允许范围内 |
| 20008 | 坐标校验 | 纬度超范围 | 检查纬度是否在允许范围内 |
| 20009 | 预报时效 | 查询天数超限 | 调小 fcst_days 或升级套餐 |
| 20014 | 接口状态 | API 未启用 | 进入控制台启用 API 服务 |
四、常见问题
Q1：试用版和付费版有什么区别？
试用版免费开通，有效期 30 天，提供 1000 次访问额度和 5 QPS；仅支持选择 1 个预报天数。付费版按套餐计费，预报天数、要素数量、额度和有效期按需定制，支持多天数组合。
Q2：历史 API 的数据时间范围是什么？
系统提供自 2025 年 1 月 1 日起至今的历史数据。详情页会根据后端可用的起报时间自动限制可选日期范围，并在页面上实时提示。
Q3：一个套餐可以同时申请多个预报天数吗？
试用版不可以，只能选 1 个预报天数。付费版支持多选，选中的多个天数会分别生成独立的订阅，各自拥有独立的要素授权。
Q4：起报时间 baseTime 的格式是什么？使用哪个时区？
格式为 yyyyMMddHH，例如2026090708 表示 2026 年 9 月 7 日 08 时起报。当前使用北京时间（UTC+8），支持 08 时和 20 时两个起报时次。国际时（UTC）支持正在规划中，后续将逐步开放。
Q5：生成链接后如何批量调用？
页面提供两种方式：
下载链接列表
.txt：每行一条 URL，方便导入其他工具下载执行脚本（Python / JavaScript）：脚本会遍历所有 URL 逐一发送请求，直接运行即可
Q6：为什么生成链接时提示「起报时间不在范围内」？
可能是您选择的日期范围或起报时次对应的起报时间点超出了数据提供范围，请调整日期或时次。
五、操作流程总览
Plaintext
┌─────────────────────────────────────────────────────────────────────────┐
│ 申请历史气象数据 API │
├─────────────────────────────────────────────────────────────────────────┤
│ ① 选择版本（试用版 / 付费版） │
│ ② 配置基础参数 │
│ · 时间分辨率（1h / 15min） │
│ · 区域范围（中国区） │
│ · 预报天数（10/15/30/45 天，付费版可多选） │
│ · 查看可提供的气象要素（只读展示） │
│ ③ 填写申请信息（所属行业、单位名称） │
│ ④ 提交申请（试用版自动通过 / 付费版人工审核） │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ 详情页：生成调用链接 + 执行脚本 │
├─────────────────────────────────────────────────────────────────────────┤
│ ① 配置参数 │
│ · 位置坐标（城市选择 / 手动输入） │
│ · 查询天数 │
│ · 日期范围（开始日期 ~ 结束日期） │
│ · 起报时次（多选，如 08 时、20 时） │
│ · AppKey（鉴权） │
│ ② 选择气象要素（搜索、全选、已选标签管理） │
│ ③ 生成链接（日期 × 时次 → 批量 URL 列表） │
│ ④ 使用链接 │
│ · 单条复制 / 下载链接列表 .txt │
│ · 生成并下载 Python / JavaScript 执行脚本 │
│ ⑤ 查阅 API 文档（请求参数、返回参数、错误码） │
└─────────────────────────────────────────────────────────────────────────┘六、API 调用示例
cURL
Bash
curl -X GET "https://api.tjweather.com/v2/history/point?baseTime=2026090108&fields=t2m,rh2m,ws10m&loc=116.39,39.90&fcst_days=10&fcst_hours=8&tz=8&t_res=1h&key=YOUR_APP_KEY&subscriptionId=YOUR_SUBSCRIPTION_ID"Python
Python
import requests
url = "https://api.tjweather.com/v2/history/point"
params = {
"baseTime": "2026090108",
"fields": "t2m,rh2m,ws10m",
"loc": "116.39,39.90",
"fcst_days": 10,
"fcst_hours": 8,
"tz": 8,
"t_res": "1h",
"key": "YOUR_APP_KEY",
"subscriptionId": "YOUR_SUBSCRIPTION_ID",
}
response = requests.get(url, params=params, timeout=30)
print(response.json())JavaScript
JavaScript
const url = new URL("https://api.tjweather.com/v2/history/point");
url.searchParams.set("baseTime", "2026090108");
url.searchParams.set("fields", "t2m,rh2m,ws10m");
url.searchParams.set("loc", "116.39,39.90");
url.searchParams.set("fcst_days", 10);
url.searchParams.set("fcst_hours", 8);
url.searchParams.set("tz", 8);
url.searchParams.set("t_res", "1h");
url.searchParams.set("key", "YOUR_APP_KEY");
url.searchParams.set("subscriptionId", "YOUR_SUBSCRIPTION_ID");
fetch(url)
.then((response) => response.json())
.then((result) => console.log(result));