一、接口能查到什么
接口盒子的这个接口一次性覆盖了实时台风 + 历史台风两类需求，而且数据粒度很细，不只是给你一个「台风名字」：
- 台风基础信息：中文名、英文名、国内编号、国际编号、代号寓意、当前状态（移动/停止）
- 逐时段实况路径：时间、经纬度、强度等级、中心气压、风速、移向、移速
- 风圈半径：7 级、10 级、12 级风圈，且按东北/东南/西南/西北四个象限分别给出
- 未来预报路径：12h / 24h / 36h / 48h / 72h / 96h / 120h 的预测位置、强度、气压、风速
换句话说，做一个台风路径动画或者影响范围评估，这套数据基本够用。
二、请求地址与参数
请求地址
https://cn.apihz.cn/api/tianqi/taifeng.php请求方式：GET 或 POST 均可。
| 参数 | 名称 | 必填 | 说明 |
|---|---|---|---|
| id | 用户 ID | 是 | 用户中心的数字 ID，如 id=10000000 |
| key | 用户 KEY | 是 | 用户中心通讯秘钥 |
| year | 年份 | 否 | 2000 年到当前年，传此参数返回当年台风列表，与 no 二选一 |
| no | 台风编号 | 否 | 传此参数返回该台风详情，与 year 二选一 |
三、两种调用模式
模式 1：传 year ------ 拿某一年台风列表
比如 year=2026，返回的是这一年的台风清单，里面包含 list.no1这个台风唯一编号，再用它去查详情。
返回核心字段：
| 字段 | 含义 |
|---|---|
| list.no1 | 台风唯一编号，用来查详情 |
| list.no2 | 国内编号 |
| list.no3 | 国际编号 |
| list.namecn | 中文代号 |
| list.nameen | 英文代号 |
| list.explanation | 代号寓意 |
| list.type | start=移动，stop=停止 |
模式 2：传 no ------ 拿单个台风完整详情
这是最常用的姿势。拿到编号后，返回的数据包非常完整：
台风头部信息
| 字段 | 含义 |
|---|---|
| no1 / no2 / no3 | 各类编号 |
| namecn / nameen | 中英文名称 |
| explanation | 名字寓意 |
| type | 当前状态 |
datas 路径数据集（每个时间点一条）
| 字段 | 含义 |
|---|---|
| time_ymdh | 时间点 |
| lat / lon | 中心经纬度 |
| position_text | 坐标描述 |
| intensity_code / intensity_text | 强度代码与中文 |
| pressure_hpa | 中心最低气压 |
| wind_speed_ms | 中心风速 |
| intensity_desc | 强度完整文本 |
| move_dir_code / move_dir_text | 移向 |
| move_speed_kmh / move_desc | 移速 |
| wind_radius | 风圈数据集 |
| forecast_babj | 未来预报节点（一般只在最后一个时间段出现） |
风圈 wind_radius 子字段
| 字段 | 含义 |
|---|---|
| grade / grade_text | 风级代码与中文 |
| ne/se/sw/nw_radius_km | 四象限半径 |
| avg_radius_km | 四向平均半径，适合快速评估影响范围 |
预报 forecast_babj 子字段
| 字段 | 含义 |
|---|---|
| forecast_hour | 未来小时数 |
| target_time_ymdh | 预报时间 |
| lat / lon | 预测位置 |
| pressure_hpa / wind_speed_ms | 预测气压风速 |
| intensity_code / intensity_text | 预测强度 |
| forecast_desc | 预报描述 |
四、返回数据示例
失败返回
{"code":400,"msg":"查询失败，请重试。"}成功返回（节选关键结构）
{
"code": 200,
"no1": "3257931",
"no2": "2609",
"no3": "2609",
"namecn": "巴威",
"nameen": "BAVI",
"explanation": "位于越南北部的山脉",
"type": "start",
"datas": [
{
"time_ymdh": "2026-07-02 08:00:00",
"lat": 11,
"lon": 160.1,
"position_text": "11.0°N, 159.4°E",
"intensity_code": "TS",
"intensity_text": "热带风暴",
"pressure_hpa": 998,
"wind_speed_ms": 18,
"intensity_desc": "热带风暴，中心气压998hPa，最大风速18m/s",
"move_dir_code": "WNW",
"move_dir_text": "西北西",
"move_speed_kmh": 20,
"move_desc": "向西北西移动，时速20公里",
"wind_radius": [
{
"grade": "30KTS",
"grade_text": "七级",
"grade_desc": "七级风圈（≥17.2m/s，风力7级）",
"ne_radius_km": 280,
"se_radius_km": 180,
"sw_radius_km": 180,
"nw_radius_km": 220,
"avg_radius_km": 215
}
]
}
],
"forecast_babj": [
{
"forecast_hour": 24,
"target_time_ymdh": "202607070600",
"lat": 17.2,
"lon": 133.4,
"pressure_hpa": 930,
"wind_speed_ms": 55,
"intensity_code": "SuperTY",
"intensity_text": "超强台风",
"forecast_desc": "24小时后：17.2°N, 133.4°E，超强台风，气压930hPa，风速55m/s"
}
]
}五、PHP 调用示例
示例 1：GET 方式（最简单）
<?php
$apiUrl = 'https://接口盒子/api/tianqi/taifeng.php';
// 替换为自己的 ID 和 KEY
$userId = '10000000';
$userKey = '15he5h15ty854j5sr152hs2';
// 方式一：查 2026 年台风列表
$params = [
'id' => $userId,
'key' => $userKey,
'year' => 2026,
'no' => ''
];
// 方式二：查指定台风详情（拿到 no1 后使用）
// $params = [
// 'id' => $userId,
// 'key' => $userKey,
// 'year'=> '',
// 'no' => '3257931'
// ];
$url = $apiUrl . '?' . http_build_query($params);
$response = file_get_contents($url);
$data = json_decode($response, true);
if ($data['code'] == 200) {
echo "查询成功\n";
echo "台风名称：{$data['namecn']} ({$data['nameen']})\n";
echo "当前状态：{$data['type']}\n";
foreach ($data['datas'] as $item) {
echo "时间：{$item['time_ymdh']}，位置：{$item['position_text']}，强度：{$item['intensity_text']}，风速：{$item['wind_speed_ms']}m/s\n";
}
// 未来预报
if (!empty($data['forecast_babj'])) {
echo "\n未来预报：\n";
foreach ($data['forecast_babj'] as $f) {
echo "{$f['forecast_desc']}\n";
}
}
} else {
echo "查询失败：{$data['msg']}\n";
}示例 2：POST 方式（cURL，更规范）
<?php
$apiUrl = 'https://接口盒子/api/tianqi/taifeng.php';
$userId = '10000000';
$userKey = '15he5h15ty854j5sr152hs2';
$postData = [
'id' => $userId,
'key' => $userKey,
'year' => 2026,
'no' => ''
];
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $apiUrl);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($postData));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
$response = curl_exec($ch);
if (curl_errno($ch)) {
echo '请求错误：' . curl_error($ch);
exit;
}
curl_close($ch);
$data = json_decode($response, true);
header('Content-Type:text/html;charset=utf-8');
if ($data['code'] == 200) {
echo '<h3>台风：' . $data['namecn'] . ' ' . $data['nameen'] . '</h3>';
echo '<p>代号寓意：' . $data['explanation'] . '</p>';
echo '<p>当前状态：' . $data['type'] . '</p>';
echo '<h4>路径数据：</h4><ul>';
foreach ($data['datas'] as $v) {
echo "<li>{$v['time_ymdh']} | {$v['position_text']} | {$v['intensity_text']} | 风速{$v['wind_speed_ms']}m/s | {$v['move_desc']}</li>";
}
echo '</ul>';
} else {
echo '接口返回错误：' . $data['msg'];
}六、Python 调用示例
示例 1：GET 方式
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
import requests
import json
class TyphoonAPI:
def __init__(self, uid, ukey):
self.url = "https://接口盒子/api/tianqi/taifeng.php"
self.uid = uid
self.ukey = ukey
def query(self, year=None, no=None):
params = {
"id": self.uid,
"key": self.ukey,
"year": year,
"no": no
}
try:
resp = requests.get(self.url, params=params, timeout=10)
resp.raise_for_status()
return resp.json()
except Exception as e:
return {"code": 400, "msg": f"请求异常: {e}"}
if __name__ == "__main__":
# 替换为自己的 ID 和 KEY
api = TyphoonAPI(uid="10000000", ukey="15he5h15ty854j5sr152hs2")
# 1. 先查年份列表
data = api.query(year=2026)
# 2. 再查某个台风详情
# data = api.query(no="3257931")
if data.get("code") == 200:
print(f"台风：{data.get('namecn')}({data.get('nameen')})")
print(f"寓意：{data.get('explanation')}")
print(f"状态：{data.get('type')}")
print("-" * 60)
for item in data.get("datas", []):
print(
f"{item['time_ymdh']} | "
f"{item['position_text']} | "
f"{item['intensity_text']} | "
f"风速{item['wind_speed_ms']}m/s | "
f"{item['move_desc']}"
)
# 风圈信息
if data["datas"]:
last = data["datas"][-1]
for wr in last.get("wind_radius", []):
print(
f"风圈：{wr['grade_text']}，"
f"四向平均半径{wr['avg_radius_km']}km，"
f"NE{wr['ne_radius_km']}/SE{wr['se_radius_km']}/"
f"SW{wr['sw_radius_km']}/NW{wr['nw_radius_km']}"
)
# 未来预报
if data.get("forecast_babj"):
print("\n未来预报：")
for f in data["forecast_babj"]:
print(f["forecast_desc"])
else:
print(f"查询失败：{data.get('msg')}")示例 2：POST 方式
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
台风 API - Python POST 示例
"""
import requests
def query_typhoon(uid, ukey, year=None, no=None):
url = "https://接口盒子/api/tianqi/taifeng.php"
data = {
"id": uid,
"key": ukey,
"year": year,
"no": no
}
try:
resp = requests.post(url, data=data, timeout=10)
resp.raise_for_status()
return resp.json()
except Exception as e:
return {"code": 400, "msg": str(e)}
if __name__ == "__main__":
UID = "10000000"
UKEY = "15he5h15ty854j5sr152hs2"
result = query_typhoon(UID, UKEY, year=2026)
if result["code"] == 200:
# 如果是列表模式
if "list" in result:
print("2026 年台风列表：")
for t in result["list"]:
print(
f"编号:{t['no1']}，"
f"中文名:{t['namecn']}，"
f"英文名:{t['nameen']}，"
f"状态:{t['type']}"
)
else:
print(f"台风详情：{result['namecn']}")
else:
print(f"错误：{result['msg']}")七、常见坑位与注意事项
- year 和 no 必须传一个：两个都空会直接失败，推荐先用 year 拿列表、再用 no1 查详情。
- 历史年份范围：支持 2000 年到当前年份，查不到 1999 年的。
- 强度代码含义：TS=热带风暴、STS=强热带风暴、TY=台风、STY=强台风、SuperTY=超强台风，做可视化时可以直接映射颜色。
- 风圈 avg_radius_km 很好用：不想画四个象限，直接用平均值就能快速圈出影响范围。