首頁›開放API
API 網關運行正常 (Edge Global) REST JSON · OAS 3.1 相容 免 Key 公開只讀

颱風說開放資料平臺 & API 參考手冊

面向氣象科研、防汛應急系統、移動客戶端與 AI 智慧體（LLM / MCP）提供低延遲、高可用的即時颱風路徑、全球熱帶氣旋及 1945–至今歷史颱風歸檔資料介面。

  • 13標準資料端點
  • 1945–2026歷史歸檔跨度
  • < 50ms邊緣緩存響應
生產環境 Base URL
https://taifengshuo.com
跨域與認證策略
CORS * · 免 Token 認證
響應格式與編碼
application/json; charset=utf-8
客戶端契約版本
X-Api-Version: v1
LIVE

在線介面調試臺 (API Explorer)

直接向當前節點發起真實 HTTP GET 請求並檢視即時返回報文
GET
READY -- ms 
// 點擊上方「發送請求」或任一介面右側的「在線調試 →」，即可在此處即時檢視真實 JSON 響應。
00

接入規範、響應信封與錯誤碼約定

Web 原生介面 (/api/*) vs 客戶端契約 (/api/v1/*)

本站同時提供兩套完全相容的只讀介面：/api/* 直接返回業務 JSON 對象，適合網頁組件與腳本快速拉取；/api/v1/* 面向 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 輪詢即時颱風介面間隔不少於 30 秒。公開引用或二次開發請註明資料來源：颱風說 (taifengshuo.com)。

code: 0請求成功 (HTTP 200)
code: 40001請求參數格式或範圍錯誤
code: 40401颱風編號或詞條資源不存在
code: 50000上游氣象源或服務端異常
01

即時颱風與全球氣旋

4 個端點
GET /api/typhoons
Edge Cache 60s · CORS *

獲取西北太平洋即時活躍颱風列表

返回當前西北太平洋及南海活躍颱風的完整實況路徑點、7/10/12級四象限風圈半徑及中、美、日、港、臺等多國官方機構預報路徑；若當前無活躍颱風，自動附帶最近編號颱風作爲參考。

核心響應欄位 (Response Schema)
欄位路徑類型欄位說明
typhoons[].code string 6位颱風編號（如 "202609"）
typhoons[].name / enname string 中文命名 / 國際英文名
typhoons[].active boolean 是否處於活躍編報狀態
typhoons[].points[] array 實況路徑序列（含 time, lat, lng, strong, power, speed, pressure, radius7/10/12）
typhoons[].forecasts object 多國氣象機構預報路徑字典（中國/日本/美國/中國香港/中國台灣）
檢視 JSON 響應示例展開 / 收起 
{
  "typhoons": [
    {
      "code": "202411",
      "name": "摩羯",
      "enname": "YAGI",
      "active": false,
      "points": [
        {
          "time": "2024-09-06 16:00:00",
          "lat": 19.7,
          "lng": 110.8,
          "strong": "超強颱風",
          "power": 17,
          "speed": 62,
          "pressure": 915,
          "moveDir": "西偏北",
          "moveSpeed": 20
        }
      ],
      "forecasts": { "中國": [...], "日本": [...], "美國": [...] }
    }
  ]
}
GET /api/typhoons/{code}
Edge Cache 120s · CORS *

查詢單個颱風完整路徑與登陸詳情

按 6 位年份編號查詢單颱風完整生命週期資料。內置三級自動回退機制：活躍緩存 → D1 1945–至今歷史歸檔庫 → 上游即時源。

請求參數 (Parameters)
參數名位置 / 類型說明與示例
code必填 path · string 6位颱風編號（YYYYNN），如 202411（摩羯）、201822（山竹）（示例：202411）
核心響應欄位 (Response Schema)
欄位路徑類型欄位說明
typhoon.code string 颱風編號（如 "202411"）
typhoon.points[] array 完整實況路徑點數組（時間升序）
typhoon.land[] array 登陸點記錄（登陸時間、位置名稱、經緯度、登陸強度）
檢視 JSON 響應示例展開 / 收起 
{
  "typhoon": {
    "code": "202411",
    "name": "摩羯",
    "enname": "YAGI",
    "startTime": "2024-09-01 20:00:00",
    "endTime": "2024-09-08 17:00:00",
    "land": [
      {
        "position": "海南省文昌市翁田鎮沿海",
        "time": "2024-09-06 16:20:00",
        "strong": "超強颱風",
        "power": 17,
        "speed": 62
      }
    ],
    "points": [ ... ]
  }
}
GET /api/global/typhoons
Edge Cache 300s · CORS *

全球海域活躍熱帶氣旋列表 (NHC / JTWC)

即時聚合北大西洋、東北太平洋、北印度洋及南半球（南印度洋/南太平洋）活躍颶風與熱帶氣旋，資料結構與 /api/typhoons 同構，每 15 分鐘與 NOAA NHC / JTWC 同步。

核心響應欄位 (Response Schema)
欄位路徑類型欄位說明
cyclones[].id string 全球唯一氣旋標識（如 "nhc-al092026"、"jtwc-sh032026"）
cyclones[].basin string 所屬海域（AL=北大西洋, EP=東北太平洋, IO=北印度洋, SH=南半球）
cyclones[].windPeriod string 風速取樣時距標準（"1min" 或 "10min"）
檢視 JSON 響應示例展開 / 收起 
{
  "cyclones": [],
  "updatedAt": "2026-10-24T16:00:00.000Z",
  "sources": ["NOAA NHC/CPHC", "US JTWC"]
}
GET /api/global/history
Edge Cache 600s · CORS *

全球海域歷史氣旋歸檔檢索

按年份或關鍵詞檢索全球非西北太平洋海域的歷史颶風/氣旋歸檔摘要（含巔峯等級、最大風速、最低氣壓與起止時間）。

請求參數 (Parameters)
參數名位置 / 類型說明與示例
year可選 query · number 按年份過濾，如 2026（示例：2026）
q可選 query · string 按英文名或 ATCF 編號模糊搜尋（示例：MILTON）
檢視 JSON 響應示例展開 / 收起 
{
  "list": [
    {
      "id": "jtwc-sh182026",
      "atcf_id": "SH182026",
      "name": "MAILA",
      "basin": "SH",
      "year": 2026,
      "peak_strong": "超強颱風",
      "max_speed": 60,
      "min_pressure": 926
    }
  ]
}
02

歷史颱風歸檔 (1945–)

4 個端點
GET /api/history/years
Edge Cache 3600s · CORS *

1945–至今歷年颱風統計總覽

返回 1945 年以來每個年份的歸檔颱風總數，適用於構建年份選擇器或年度氣候趨勢折線圖。

檢視 JSON 響應示例展開 / 收起 
{
  "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 *

查詢指定年份全部颱風列表

返回指定年份（1945–2026）生成的所有西北太平洋颱風概要資訊，包含巔峯強度、最大風速、最低中心氣壓與起止時間。

請求參數 (Parameters)
參數名位置 / 類型說明與示例
year必填 path · number 4位年份（1945–2026）（示例：2024）
檢視 JSON 響應示例展開 / 收起 
{
  "year": 2024,
  "typhoons": [
    {
      "code": "202411",
      "name": "摩羯",
      "enname": "YAGI",
      "strong": "超強颱風",
      "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/today
Edge Cache 3600s · CORS *

歷史上的今天活躍知名颱風

查詢 1945 年以來在當年今日（MM-DD）處於活躍狀態的知名歷史颱風列表。

檢視 JSON 響應示例展開 / 收起 
{
  "date": "10-24",
  "typhoons": [ ... ]
}
03

客戶端穩定契約 (API v1)

3 個端點
GET /api/v1/bootstrap
Public 60s · X-Api-Version: v1

客戶端冷啓動聚合包 (Bootstrap)

面向 iOS / Android / HarmonyOS 及第三方小程式的首屏冷啓動聚合介面：1 次請求返回站點配置、置頂公告、當前活躍颱風摘要、今日 AI 晨報及各端最新版本資訊。統一包裹於 { code: 0, msg: "ok", data, ts } 標準信封。

核心響應欄位 (Response Schema)
欄位路徑類型欄位說明
code number 狀態碼：0 表示成功，非 0 爲業務錯誤碼
data.activeTyphoons[] array 當前活躍颱風輕量摘要（含最新經緯度、風速、氣壓、等級）
data.briefing string 颱風君今日氣象晨報文本
data.version object Android / iOS / HarmonyOS 最新版本號與下載地址
檢視 JSON 響應示例展開 / 收起 
{
  "code": 0,
  "msg": "ok",
  "data": {
    "activeTyphoons": [],
    "briefing": "今日西北太平洋洋麪整體平靜...",
    "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 颱風快訊分頁列表 (v1)

分頁獲取已發佈的即時颱風快訊流（含 AI 颱風君專業點評、結構化實況快照與發佈時間），支援下拉重新整理與無限滾動。

請求參數 (Parameters)
參數名位置 / 類型說明與示例
page可選 query · number 頁碼（從 1 開始，預設 1）（示例：1）
size可選 query · number 每頁條數（1–50，預設 20）（示例：5）
檢視 JSON 響應示例展開 / 收起 
{
  "code": 0,
  "msg": "ok",
  "data": {
    "page": 1,
    "size": 5,
    "total": 420,
    "list": [
      {
        "id": 812,
        "title": "颱風外圍環流影響華南沿海...",
        "ai_comment": "颱風君點評：...",
        "flash_at": "2026-10-24 14:30:00"
      }
    ]
  },
  "ts": 1761321600000
}
GET /api/v1/knowledge
Edge Cache 600s · X-Api-Version: v1

颱風百科詞條全量目錄與詳情 (v1)

獲取颱風說 80 篇專業防災與氣象百科詞條列表；傳入 /api/v1/knowledge/{slug} 可直接拉取單篇詞條的完整 Markdown 正文與 SEO 摘要。

檢視 JSON 響應示例展開 / 收起 
{
  "code": 0,
  "msg": "ok",
  "data": {
    "list": [
      {
        "slug": "hk-typhoon-signals-explained",
        "title": "香港8號風球、10號風球是什麼意思？與內地藍黃橙紅預警對照表",
        "summary": "香港天文台風球信號（1號、3號、8號、9號、10號）代表什麼風力..."
      }
    ]
  },
  "ts": 1761321600000
}
04

AI 摘要與快訊百科

2 個端點
GET /api/llm/summary
Edge Cache 120s · CORS *

AI 大模型 / Agent 專用即時颱風態勢摘要

專爲大語言模型（LLM Function Calling / MCP 外掛 / 智慧體）設計的零冗餘即時態勢介面，同時返回自然語言態勢簡報（summary）與精簡結構化資料（typhoons + global）。

檢視 JSON 響應示例展開 / 收起 
{
  "updatedAt": "2026-10-24T16:00:00.000Z",
  "summary": "截至當前，西北太平洋及南海無編號活躍颱風...",
  "typhoons": [],
  "global": []
}
GET /api/seo/news
Edge Cache 300s · CORS *

颱風即時監測動態播報流

返回基於即時氣象報文自動生成的颱風位置、風速、氣壓與多機構預報綜述，可通過 ?code=YYYYNN 過濾指定颱風。

請求參數 (Parameters)
參數名位置 / 類型說明與示例
code可選 query · string 可選，按6位颱風編號過濾（示例：202411）
檢視 JSON 響應示例展開 / 收起 
{
  "items": [
    {
      "code": "202411",
      "name": "摩羯",
      "title": "超強颱風摩羯（202411）最新位置與路徑分析",
      "summary": "中心最大風速62m/s，中心最低氣壓915hPa..."
    }
  ]
}