API gateway operational (Edge Global) REST JSON · OAS 3.1 compatible Public read-only access without a Key

TyphoonSays Open Data Platform & API Reference

Catering to meteorological research, flood emergency systems, the Moving app, and AI agents (LLM / MCP) with low-latency, highly available APIs for Live Typhoons, Global Tropical Cyclones, and the 1945–present History archive.

13Standard data endpoints
1945–2026Archive coverage
< 50msEdge-cached responses

Production Base URL

https://taifengshuo.com

CORS and authentication policy

CORS * · No Token authentication required

Response format and encoding

application/json; charset=utf-8

Client contract version

X-Api-Version: v1

LIVE

在线接口调试台 (API Explorer)

直接 toward current 节点发起真实 HTTP GET 请求并View live 返回报文

GET

READY -- ms

// 点击上方「发送请求」或任一接口右侧的「在线调试 →」, 即可在此处live View 真实 JSON 响应.

接入规范, 响应信封与错误码约定

Web 原生接口 (`/api/`) vs 客户端契约 (`/api/v1/`)

CMA同时提供两套完全兼容的只读接口: /api/* 直接返回业务 JSON 对象, 适合网页组件与脚本快速拉取; /api/v1/* 面 toward iOS / Android / 鸿蒙 App 与生产级服务, 统一包裹在 {"code":0,"msg":"ok","data":...,"ts":1761321600000} 标准信封中, 并携带 X-Api-Version: v1 响应头.

缓存策略, 并发限流与数据署名

所有公开接口均通过 Cloudflare 全球边缘节点缓存 (Cache-Control: public, max-age=60~3600) , 支持全量 CORS 预检 (OPTIONS) . 建议客户端遵守边缘缓存周期, 单 IP 轮询Live Typhoons接口间隔不少 at 30 秒. 公开引用或二次开发请注明Data sources: TyphoonSays (taifengshuo.com).

code: 0请求成功 (HTTP 200)

code: 40001请求参数格式或范围错误

code: 40401Typhoon code或词条资源不存在

code: 50000上游气象源或服务端异常

Live Typhoons与Global Cyclones

4 个端点

GET /api/typhoons

Edge Cache 60s · CORS *

获取Northwest Pacificlive ActiveTyphoon 列表

返回current Northwest Pacific及S海ActiveTyphoon 的完整实况 track points, 7/10/12级四象限风圈半径及中, 美, 日, 港, 台等多国官方机构Forecast路径; 若current 无ActiveTyphoon , 自动附带最近codeTyphoon 作为参考.

核心响应字段 (Response Schema)

字段路径	类型	字段说明
typhoons[].code	string	6位Typhoon code (如 "202609")
typhoons[].name / enname	string	中文命名 / 国际英文名
typhoons[].active	boolean	是否处 at Active编报状态
typhoons[].points[]	array	实况路径序列 (含 time, lat, lng, strong, power, speed, pressure, radius7/10/12)
typhoons[].forecasts	object	多国气象机构Forecast路径字典 (China/Japan/USA/Hong Kong, China/Taiwan, China)

View JSON 响应示例Expand / Collapse

{
  "typhoons": [
    {
      "code": "202411",
      "name": "Yagi",
      "enname": "YAGI",
      "active": false,
      "points": [
        {
          "time": "2024-09-06 16:00:00",
          "lat": 19.7,
          "lng": 110.8,
          "strong": "Super Typhoon",
          "power": 17,
          "speed": 62,
          "pressure": 915,
          "moveDir": "WNW",
          "moveSpeed": 20
        }
      ],
      "forecasts": { "China": [...], "Japan": [...], "USA": [...] }
    }
  ]
}

GET /api/typhoons/{code}

Edge Cache 120s · CORS *

查询单个Typhoon 完整路径与Landfalldetails

按 6 位年份code查询单Typhoon 完整生命周期数据. 内置三级自动回退机制: Active缓存 → D1 1945–至今Archive库 → 上游live 源.

请求参数 (Parameters)

参数名	Position / 类型	说明与示例
code必填	path · string	6位Typhoon code (YYYYNN) , 如 202411 (Yagi) , 201822 (Mangkhut) (示例: `202411`)

核心响应字段 (Response Schema)

字段路径	类型	字段说明
typhoon.code	string	Typhoon code (如 "202411")
typhoon.points[]	array	完整实况 track points数组 (Time升序)
typhoon.land[]	array	Landfall点记录 (LandfallTime, Position名称, 经纬度, LandfallIntensity)

View JSON 响应示例Expand / Collapse

{
  "typhoon": {
    "code": "202411",
    "name": "Yagi",
    "enname": "YAGI",
    "startTime": "2024-09-01 20:00:00",
    "endTime": "2024-09-08 17:00:00",
    "land": [
      {
        "position": "Hainan文昌 City翁田镇coastal ",
        "time": "2024-09-06 16:20:00",
        "strong": "Super Typhoon",
        "power": 17,
        "speed": 62
      }
    ],
    "points": [ ... ]
  }
}

GET /api/global/typhoons

Edge Cache 300s · CORS *

全球海域ActiveTropical Cyclone 列表 (NHC / JTWC)

live 聚合North Atlantic, East Pacific, North Indian Ocean及Southern Hemisphere (South Indian Ocean/South Pacific) ActiveHurricane 与Tropical Cyclone , 数据结构与 /api/typhoons 同构, 每 15 分钟与 NOAA NHC / JTWC 同步.

核心响应字段 (Response Schema)

字段路径	类型	字段说明
cyclones[].id	string	全球唯一气旋标识 (如 "nhc-al092026", "jtwc-sh032026")
cyclones[].basin	string	所属海域 (AL=North Atlantic, EP=East Pacific, IO=North Indian Ocean, SH=Southern Hemisphere)
cyclones[].windPeriod	string	wind speed取样时About 标准 ("1min" 或 "10min")

View JSON 响应示例Expand / Collapse

{
  "cyclones": [],
  "updatedAt": "2026-10-24T16:00:00.000Z",
  "sources": ["NOAA NHC/CPHC", "US JTWC"]
}

GET /api/global/history

Edge Cache 600s · CORS *

全球海域历史Cyclone archive检索

按年份或关键词检索全球非Northwest Pacific海域的历史Hurricane /Cyclone archive摘要 (含巅峰等级, Max Wind, 最低气压与起止Time) .

请求参数 (Parameters)

参数名	Position / 类型	说明与示例
year可选	query · number	按年份过滤, 如 2026 (示例: `2026`)
q可选	query · string	按英文名或 ATCF code模糊Search (示例: `MILTON`)

View JSON 响应示例Expand / Collapse

{
  "list": [
    {
      "id": "jtwc-sh182026",
      "atcf_id": "SH182026",
      "name": "MAILA",
      "basin": "SH",
      "year": 2026,
      "peak_strong": "Super Typhoon",
      "max_speed": 60,
      "min_pressure": 926
    }
  ]
}

History归档 (1945–)

4 个端点

GET /api/history/years

Edge Cache 3600s · CORS *

1945–至今历 Typhoon 统计总览

返回 1945 年以来每个年份的归档Typhoon 总数, 适用 at 构建年份Select 器或年度气候Trend折线图.

View JSON 响应示例Expand / Collapse

{
  "years": [
    { "year": 2026, "count": 30 },
    { "year": 2025, "count": 26 },
    { "year": 2024, "count": 26 },
    { "year": 1945, "count": 26 }
  ]
}

GET /api/history/{year}

Edge Cache 3600s · CORS *

查询指定年份全部Typhoon 列表

返回指定年份 (1945–2026) formed的所有Northwest PacificTyphoon 概要信息, 包含peak intensity, Max Wind, 最低Pressure与起止Time.

请求参数 (Parameters)

参数名	Position / 类型	说明与示例
year必填	path · number	4位年份 (1945–2026) (示例: `2024`)

View JSON 响应示例Expand / Collapse

{
  "year": 2024,
  "typhoons": [
    {
      "code": "202411",
      "name": "Yagi",
      "enname": "YAGI",
      "strong": "Super Typhoon",
      "max_speed": 68,
      "min_pressure": 905,
      "start_time": "2024-09-01 14:00:00",
      "end_time": "2024-09-08 17:00:00"
    }
  ]
}

GET /api/history/search/{keyword}

Edge Cache 600s · CORS *

按中文名 / 英文名 / codeSearchHistory

支持按中文名 (如“Mangkhut”“Rammasun”) , 国际英文名 (如“MANGKHUT”“HAIYAN”) 或code前缀快速检索History (单次最多返回 50 条) .

请求参数 (Parameters)

参数名	Position / 类型	说明与示例
keyword必填	path · string	Typhoon 中英文名称或code片段 (示例: `Mangkhut`)

View JSON 响应示例Expand / Collapse

{
  "results": [
    {
      "code": "201822",
      "year": 2018,
      "name": "Mangkhut",
      "enname": "MANGKHUT",
      "strong": "Super Typhoon",
      "max_speed": 65,
      "min_pressure": 910
    }
  ]
}

GET /api/history/today

Edge Cache 3600s · CORS *

On This Day in HistoryActive知名Typhoon

查询 1945 年以来在当年今日 (MM-DD) 处 at Active状态的知名History列表.

View JSON 响应示例Expand / Collapse

{
  "date": "10-24",
  "typhoons": [ ... ]
}

客户端稳定契约 (API v1)

3 个端点

GET /api/v1/bootstrap

Public 60s · X-Api-Version: v1

客户端冷启动聚合包 (Bootstrap)

面 toward iOS / Android / HarmonyOS 及第三方小程序的首屏冷启动聚合接口: 1 次请求返回站点配置, 置顶公告, Active Typhoons摘要, 今日 AI Briefing及各端最新版本信息. 统一包裹 at { code: 0, msg: "ok", data, ts } 标准信封.

核心响应字段 (Response Schema)

字段路径	类型	字段说明
code	number	状态码: 0 表示成功, 非 0 为业务错误码
data.activeTyphoons[]	array	Active Typhoons轻量摘要 (含最新经纬度, wind speed, 气压, 等)
data.briefing	string	Typhoon Bot今日气象Briefing文本
data.version	object	Android / iOS / HarmonyOS 最新版本号与下载地址

View JSON 响应示例Expand / Collapse

{
  "code": 0,
  "msg": "ok",
  "data": {
    "activeTyphoons": [],
    "briefing": "今日Northwest Pacific洋面整体平静...",
    "version": {
      "api": "v1",
      "android": { "latest": "1.2.0", "min": "1.0.0" },
      "ios": { "latest": "1.2.0", "min": "1.0.0" }
    }
  },
  "ts": 1761321600000
}

GET /api/v1/flash

Edge Cache 60s · X-Api-Version: v1

7×24 Typhoon Flash News分页列表 (v1)

分页获取已发布的Live Typhoons快讯流 (含 AI Typhoon Bot专业点评, 结构化实况快照与发布Time) , 支持下拉刷新与无限滚动.

请求参数 (Parameters)

参数名	Position / 类型	说明与示例
page可选	query · number	页码 (从 1 开始, 默认 1) (示例: `1`)
size可选	query · number	每页条数 (1–50, 默认 20) (示例: `5`)

View JSON 响应示例Expand / Collapse

{
  "code": 0,
  "msg": "ok",
  "data": {
    "page": 1,
    "size": 5,
    "total": 420,
    "list": [
      {
        "id": 812,
        "title": "Typhoon 外围环流影响华Scoastal ...",
        "ai_comment": "Typhoon Bot点评: ...",
        "flash_at": "2026-10-24 14:30:00"
      }
    ]
  },
  "ts": 1761321600000
}

GET /api/v1/knowledge

Edge Cache 600s · X-Api-Version: v1

Typhoon Wiki词条全量目录与details (v1)

获取TyphoonSays 80 篇专业防灾与气象Wiki词条列表; 传入 /api/v1/knowledge/{slug} 可直接拉取单篇词条的完整 Markdown 正文与 SEO 摘要.

View JSON 响应示例Expand / Collapse

{
  "code": 0,
  "msg": "ok",
  "data": {
    "list": [
      {
        "slug": "hk-typhoon-signals-explained",
        "title": "Hong Kong8号风球, 10号风球是什么意思? 与内地蓝黄橙红预警对照表",
        "summary": "HKO (Hong Kong)风球信号 (1号, 3号, 8号, 9号, 10号) 代表什么wind force..."
      }
    ]
  },
  "ts": 1761321600000
}

AI 摘要与快讯Wiki

2 个端点

GET /api/llm/summary

Edge Cache 120s · CORS *

AI 大模型 / Agent 专用Live Typhoons态势摘要

专为大语言模型 (LLM Function Calling / MCP 插件 / 智能体) 设计的零冗余live 态势接口, 同时返回自然语言态势简报 (summary) 与精简结构化数据 (typhoons + global) .

View JSON 响应示例Expand / Collapse

{
  "updatedAt": "2026-10-24T16:00:00.000Z",
  "summary": "截至current , Northwest Pacific及S海无codeActiveTyphoon ...",
  "typhoons": [],
  "global": []
}

GET /api/seo/news

Edge Cache 300s · CORS *

Typhoon live 监测动态播报流

返回基 at live 气象报文自动 formed的Typhoon Position, wind speed, 气压与多机构Forecast综述, 可通过 ?code=YYYYNN 过滤指定Typhoon .

请求参数 (Parameters)

参数名	Position / 类型	说明与示例
code可选	query · string	可选, 按6位Typhoon code过滤 (示例: `202411`)

View JSON 响应示例Expand / Collapse

{
  "items": [
    {
      "code": "202411",
      "name": "Yagi",
      "title": "Super TyphoonYagi (202411) latest position与路径分析",
      "summary": "中心Max Wind62m/s, 中心最低气压915hPa..."
    }
  ]
}

Track Typhoon

Research

Join the community

About

TyphoonSays Open Data Platform & API Reference

在线接口调试台 (API Explorer)

接入规范, 响应信封与错误码约定

Web 原生接口 (`/api/`) vs 客户端契约 (`/api/v1/`)

缓存策略, 并发限流与数据署名

Live Typhoons与Global Cyclones

获取Northwest Pacificlive ActiveTyphoon 列表

查询单个Typhoon 完整路径与Landfalldetails

全球海域ActiveTropical Cyclone 列表 (NHC / JTWC)

全球海域历史Cyclone archive检索

History归档 (1945–)

1945–至今历 Typhoon 统计总览

查询指定年份全部Typhoon 列表

按中文名 / 英文名 / codeSearchHistory

On This Day in HistoryActive知名Typhoon

客户端稳定契约 (API v1)

客户端冷启动聚合包 (Bootstrap)

7×24 Typhoon Flash News分页列表 (v1)

Typhoon Wiki词条全量目录与details (v1)

AI 摘要与快讯Wiki

AI 大模型 / Agent 专用Live Typhoons态势摘要

Typhoon live 监测动态播报流

Web 原生接口 (/api/*) vs 客户端契约 (/api/v1/*)

缓存策略, 并发限流与数据署名

获取Northwest Pacificlive ActiveTyphoon 列表

查询单个Typhoon 完整路径与Landfalldetails

全球海域ActiveTropical Cyclone 列表 (NHC / JTWC)

全球海域历史Cyclone archive检索

1945–至今历 Typhoon 统计总览

查询指定年份全部Typhoon 列表

按中文名 / 英文名 / codeSearchHistory

On This Day in HistoryActive知名Typhoon

客户端冷启动聚合包 (Bootstrap)

7×24 Typhoon Flash News分页列表 (v1)

Typhoon Wiki词条全量目录与details (v1)

AI 大模型 / Agent 专用Live Typhoons态势摘要

Typhoon live 监测动态播报流

Web 原生接口 (`/api/`) vs 客户端契约 (`/api/v1/`)