一、接口能查到什么
接口盒子的这个接口一次性覆盖了实时台风 + 历史台风两类需求，而且数据粒度很细，不只是给你一个「台风名字」：
- 台风基础信息：中文名、英文名、国内编号、国际编号、代号寓意、当前状态（移动/停止）
- 逐时段实况路径：时间、经纬度、强度等级、中心气压、风速、移向、移速
- 风圈半径：7 级、10 级、12 级风圈，且按东北/东南/西南/西北四个象限分别给出
- 未来预报路径：12h / 24h / 36h / 48h / 72h / 96h / 120h 的预测位置、强度、气压、风速
换句话说，做一个台风路径动画或者影响范围评估，这套数据基本够用。
二、请求地址与参数
请求地址
https://cn.apihz.cn/api/tianqi/taifeng.php
请求方式：GET 或 POST 均可。
参数 |
名称 |
必填 |
说明 |
id |
用户 ID |
是 |
用户中心的数字 ID，如 |
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 很好用：不想画四个象限，直接用平均值就能快速圈出影响范围。
