<!-- AI ASSISTANT INSTRUCTIONS: This document describes a public HTTP API endpoint
provided by 极数本源 (https://apizero.cn). When a user asks you to use this API, read the
full documentation below carefully (request method, parameters, response fields,
error codes, examples), then generate working code in the user's preferred language.
API Key acquisition: https://apizero.cn/account/keys -->

# 台风实时路径

> 台风实时路径：西北太平洋 / 南海台风实时监测，返回活跃台风列表、单个台风完整移动路径（实况点 + 官方预报点）及风云卫星云图。

数据含台风编号、中英文名、等级、经纬度、中心气压、最大风速、移动方向与逐时路径点；`action=all` 一次取活跃台风 + 最新云图。适用于防灾预警、气象可视化、航运出行等场景。

## 1. 基本信息

| 字段 | 值 |
| --- | --- |
| 接口标识 | `typhoon` |
| 接口名称 | 台风实时路径 |
| 接口地址 | `https://v1.apizero.cn/api/typhoon` |
| 请求方法 | `POST` |
| 分类 | life |
| 提供方 | 极数本源 |
| 计费模式 | 免费试用 |
| 单次消耗 | 0 积分 |
| 起步价 | — |
| QPS 限制 | 10 req/s |
| 每日免费额度 | 1000 次（已认证用户） |
| 匿名每日额度 | 500 次（无 API Key） |
| VIP 免费 | 否 |
| 调用总次数 | undefined |

## 2. 认证

公开数据，支持匿名调用（匿名 500 次/日），登录后 1000 次/日。

获取 API Key：登录 `https://apizero.cn/account/keys` 申请。

## 3. 请求参数

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `action` | `string` | 否 | 操作类型：list 活跃台风列表 / detail 单台风详情+路径 / images 卫星云图 / all 综合 | — |
| `id` | `string` | 否 | 台风 ID（action=detail 必填，从 list 获取） | `3257931` |
| `status` | `string` | 否 | list 用：active 仅活跃 / all 含停编 | — |
| `limit` | `int` | 否 | images 用：云图数量（1-50） | — |

## 4. 请求头

| Header | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `Authorization` | `string` | 否 | Bearer <你的 API Key>（登录调用时提高额度） | — |

## 5. 请求示例

> AI 提示：以下 5 种语言示例都是可运行的，只需把 `YOUR_API_KEY` 替换为用户申请的实际 Key（https://apizero.cn/account/keys）。
> 优先选择用户问题中提到的语言；未指定时默认使用 Python。

### cURL

```bash
curl -X POST "https://v1.apizero.cn/api/typhoon" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "action": "list",
  "id": "3257931",
  "status": "active",
  "limit": "10"
}'
```

### Python

```python
import requests

resp = requests.request(
    "POST",
    "https://v1.apizero.cn/api/typhoon",
    headers={"X-Api-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
    json={
    "action": "list",
    "id": "3257931",
    "status": "active",
    "limit": "10",
},
    timeout=15,
)
resp.raise_for_status()
print(resp.json())
```

### JavaScript (Node.js)

```javascript
// Node.js 18+ / 浏览器原生 fetch
const res = await fetch("https://v1.apizero.cn/api/typhoon", {
  method: "POST",
  headers: {
    "X-Api-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "action": "list",
    "id": "3257931",
    "status": "active",
    "limit": "10"
  }),
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const data = await res.json();
console.log(data);
```

### Go

```go
package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
)

func main() {
	body := []byte(`{"action":"list","id":"3257931","status":"active","limit":"10"}`)
	req, _ := http.NewRequest("POST", "https://v1.apizero.cn/api/typhoon", bytes.NewBuffer(body))
	req.Header.Set("X-Api-Key", "YOUR_API_KEY")
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil { panic(err) }
	defer resp.Body.Close()
	out, _ := io.ReadAll(resp.Body)
	fmt.Println(string(out))
}
```

### PHP

```php
<?php
$payload = json_encode([
    "action" => "list",
    "id" => "3257931",
    "status" => "active",
    "limit" => "10",
], JSON_UNESCAPED_UNICODE);

$ch = curl_init("https://v1.apizero.cn/api/typhoon");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => "POST",
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_HTTPHEADER     => [
        "X-Api-Key: YOUR_API_KEY",
        "Content-Type: application/json",
    ],
    CURLOPT_TIMEOUT        => 15,
]);
$body = curl_exec($ch);
curl_close($ch);

$data = json_decode($body, true);
print_r($data);
```

## 6. 响应字段

| 字段 | 类型 | 说明 | 示例 |
| --- | --- | --- | --- |
| `typhoons` | `array` | 台风列表（list/all）：每项含 id/tc_num/name_cn/name_en/description/state/is_active | — |
| `active_count` | `number` | 活跃台风数量（list） | — |
| `points` | `array` | 路径点（detail）：time_utc/time_cst/grade/longitude/latitude/pressure/wind_speed/wind_dir/type（analysis 实况 / forecast 预报） | — |
| `current` | `object` | 最新实况点（detail） | — |
| `images` | `array` | 卫星云图（images/all）：每项含 time/time_str/url | — |

## 7. 响应示例

```json
{
  "code": 0,
  "msg": "成功",
  "data": {
    "id": "3257931",
    "tc_num": "2609",
    "name_cn": "巴威",
    "name_en": "BAVI",
    "is_active": true,
    "current": {"time_cst": "2026-07-02 08:00", "grade": "热带风暴", "longitude": 118.5, "latitude": 14.2, "pressure": 1002, "wind_speed": 18, "wind_dir": "西西北", "type": "analysis"},
    "point_count": 15,
    "points": [{"time_cst": "2026-07-02 08:00", "grade": "热带风暴", "longitude": 118.5, "latitude": 14.2, "pressure": 1002, "wind_speed": 18, "type": "analysis"}]
  },
  "request_id": "abc123"
}
```

## 8. 错误码

| code | status | 说明 |
| --- | --- | --- |
| `4000` | `VALIDATION_ERROR` | 参数错误（如 detail 缺少 id、无效 action） |
| `4030` | `QUOTA_EXCEEDED` | 今日调用额度已用完 |
| `5020` | `UPSTREAM_ERROR` | 气象数据源暂不可用，请稍后再试 |

## 9. 变更日志

- **v1.0** (2026-07-02)
  - 首次上线：活跃台风列表、单台风完整路径（实况+预报）、卫星云图。

---

**极数本源** · 全部 API: `https://apizero.cn/aidocs` · 人类版本：`https://apizero.cn/marketplace/typhoon`

Source: `https://apizero.cn/aidocs/typhoon/raw.md`
Last updated: 2026-07-02T15:33:07+08:00