适用场景与数据价值
在西北太平洋和南海海域，台风是影响沿海城市与航线安全的主要气象灾害之一。实时获取台风位置、强度、路径预测以及卫星云图，对于防灾减灾、航运调度、能源海上平台监控等场景至关重要。
台风实时路径API提供了结构化的JSON数据，覆盖从热带低压到超强台风的全等级信息，并包含官方预报点与实况分析点。开发者可以通过标准化请求获取当前活跃台风列表、单个台风的完整移动路径，以及最新的风云卫星云图。
典型使用场景包括：
- 气象可视化大屏：将台风路径点与云图叠加在地图上，展示动态演变过程。
- 航海安全系统：根据实时位置与预报点评估航线风险，自动触发告警。
- 防灾预警平台：定时拉取活跃台风列表，结合本地GIS系统推送受影响区域预警。
- 行业数据研究：对历史路径进行复盘分析，改进台风预测模型。
接口能力边界
该API为POST请求，基础地址：https://v1.apizero.cn/api/typhoon。核心能力体现在action参数上，不同请求组合覆盖四种数据粒度：
| action 值 | 返回内容 | 典型用法 |
|---|---|---|
list | 当前活跃台风列表（名称、编号、最新位置、等级） | 快速浏览所有活跃台风 |
detail | 单个台风的完整路径点（实况+预报）、历史点数量 | 展示特定台风移动轨迹 |
images | 风云卫星云图列表（时间、URL） | 获取云图素材进行可视化 |
all | 活跃台风列表 + 最新一张云图 | 客户端一次性获取关键信息 |
注意：
detail和images需要搭配id参数（台风ID从list响应中获取）；images还可通过limit控制返回云图数量（1-50）。list支持status筛选：active仅返回活跃台风，all包含已停编但仍在监测范围内的历史台风。
QPS与鉴权限额
接口默认QPS限制为10次/秒，适用于大多数初级到中级规模的应用。如果需要在请求中携带鉴权标头（Authorization: Bearer <API Key>），可以提升调用额度。鉴权方式采用Bearer Token，需提前获取API Key。
请求参数与鉴权
Header参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
Authorization | string | 否 | Bearer <你的API Key>，登录调用时提高额度 |
Content-Type | string | 是 | 固定为application/json |
请求体（JSON object）
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
action | string | 否 | 操作类型：list/detail/images/all，不传默认为list |
id | string | 否 | 台风ID（detail和images必填） |
status | string | 否 | list下使用：active仅活跃，all含停编 |
limit | number | 否 | images下使用：云图数量1-50，不传默认值以文档为准 |
curl与代码接入示例
以下示例使用shell变量$API_KEY和$TYPHOON_ID，避免硬编码。
1. 获取活跃台风列表
curl -sS -X POST \ -H "Content-Type: application/json" \ -d '{"action":"list","status":"active"}' \ "https://v1.apizero.cn/api/typhoon"2. 获取单个台风详情（需先通过list获得台风ID）
# 假设台风ID为3257931 TYPHOON_ID="3257931" curl -sS -X POST \ -H "Content-Type: application/json" \ -d "{\"action\":\"detail\",\"id\":\"$TYPHOON_ID\"}" \ "https://v1.apizero.cn/api/typhoon"3. 获取最近3张云图
curl -sS -X POST \ -H "Content-Type: application/json" \ -d '{"action":"images","id":"3257931","limit":3}' \ "https://v1.apizero.cn/api/typhoon"4. 使用Python requests库
import requests import json url = "https://v1.apizero.cn/api/typhoon" headers = {"Content-Type": "application/json"} # 获取列表 payload = {"action": "list", "status": "active"} resp = requests.post(url, headers=headers, json=payload) data = resp.json() print(json.dumps(data, indent=2, ensure_ascii=False))返回值解读
成功响应的HTTP状态码为200，内容类型为JSON，顶层结构如下：
{ "code": 0, "msg": "成功", "request_id": "abc123", "data": { ... } }其中request_id可用于排查问题，code为0表示成功，非0表示失败。
data字段详解（以detail为例）
| 字段名 | 类型 | 说明 |
|---|---|---|
id | string | 台风唯一ID |
tc_num | string | 台风编号，如2609表示2026年第9号 |
name_cn | string | 台风中文名 |
name_en | string | 台风英文名 |
is_active | boolean | 是否仍然活跃 |
point_count | number | 路径点总数（实况+预报） |
current | object | 最新时刻的实况分析（或预报）点，包含：grade（等级）、latitude/longitude、pressure（中心气压hPa）、wind_speed（最大风速m/s）、wind_dir（移动方向）、time_cst（北京时）、type（analysis=实况，forecast=预报） |
points | array | 所有路径点数组，每个元素结构同current（不含wind_dir） |
等级映射（常见值）：热带低压、热带风暴、强热带风暴、台风、强台风、超强台风。
当action为list时，data是一个数组，每个元素包含id、name_cn、name_en、tc_num、grade、latitude、longitude、wind_speed、pressure、time_cst等简要信息。
当action为images时，data为对象，包含urls数组，每项含time_cst和url。
常见错误与处理
| 错误表现 | 可能原因 | 排查方式 |
|---|---|---|
code非0（如1001） | 请求参数格式错误 | 检查JSON是否合法，必填字段是否缺失 |
| 返回空列表 | 当前无活跃台风，或status参数值不当 | 尝试status":"all"或换时间请求 |
| 返回404 | 请求地址错误 | 确认URL末尾无多余斜杠或拼写 |
| 返回429 | 请求频率超过QPS 10次/秒 | 加入限流逻辑，或使用鉴权提升额度 |
| 返回403 | API Key无效或额度不足 | 检查Header中Authorization格式是否正确 |
msg为“台风ID不存在” | id参数与数据库不匹配 | 重新通过list获取最新有效ID |
工程化注意事项
1. 缓存策略
- 台风列表：活跃台风变化频率不高（数十分钟到数小时），可设置缓存TTL为5~10分钟，减少无效请求。
- 路径点：对于同一个台风，路径点按时间递增，后端会持续追加新点。建议客户端只增量拉取新点，例如记录上次拉取的最后时间戳，后续只请求
detail获取全部点再本地去重。 - 云图：云图变动以小时计，缓存30分钟以上通常可接受。
2. 异常重试与幂等
由于返回数据对同一id在短时间内是持久一致的（除非台风位置更新），请求可以安全重试。推荐指数退避重试：第1次重试等待1秒，第2次2秒，第3次4秒，最多3次。
3. 数据可视化预处理
路径点数组points按时间升序排列，可直接连线绘制轨迹。type字段区分实况与预报，前端可以用不同线型（实线/虚线）区分。grade可用于着色（如根据等级映射颜色）。
4. 鉴权安全
- 不要在客户端代码中硬编码API Key。通过后端代理转发请求，或使用环境变量注入。
- 如果使用Bearer Token，务必通过HTTPS传输。
5. 时间处理
time_cst字段为北京时间（东八区，无时区后缀）。如果需要转换为UTC或其他时区，建议使用Asia/Shanghai时区解析。格式如"2026-07-02 08:00"，可直接用datetime.strptime处理。
参考文档
- 原始文档：https://apizero.cn/aidocs/typhoon/raw.md
- 文档页：https://apizero.cn/aidocs/typhoon
