API 文檔 - 台灣 AQI 全時排行榜

API 文檔 v1

🌐 API 基礎 URL

http://YOUR_SERVER_IP:5000

請將 YOUR_SERVER_IP 替換為您的伺服器 IP 或網域名稱

🔐 認證說明

所有 API 端點都需要提供 API Key，可透過以下兩種方式：

Header: X-API-Key: your-api-key
Query Parameter: ?api_key=your-api-key

預設 Demo Key: demo-key-12345（每小時 10,000 次請求）

速率限制: 根據 API Key 而定，超過限制會回傳 429 錯誤

如何取得 API Key: 請聯繫系統管理員或使用預設 demo key 進行測試

GET /api/v1/stations

取得測站列表

參數：

county (選填): 縣市名稱，例如 "臺北市"

範例：

/api/v1/stations?county=雲林縣&api_key=demo-key-12345

GET /api/v1/observations

查詢觀測資料

參數：

start (必需): 起始日期 YYYY-MM-DD
end (必需): 結束日期 YYYY-MM-DD
siteid (選填): 測站代碼
county (選填): 縣市名稱
limit (選填): 筆數上限，預設 1000
offset (選填): 分頁偏移，預設 0
order (選填): 排序方式（aqi_desc/aqi_asc/time_desc/time_asc），預設 aqi_desc

範例：

/api/v1/observations?start=2025-10-20&end=2025-10-30&county=雲林縣&limit=100&api_key=demo-key-12345

cURL 範例（使用 Header）：

curl -H "X-API-Key: demo-key-12345" "http://127.0.0.1:5000/api/v1/observations?start=2025-10-20&end=2025-10-30&county=雲林縣"

GET /api/v1/ranking

排行榜查詢

參數：

start (必需): 起始日期 YYYY-MM-DD
end (必需): 結束日期 YYYY-MM-DD
top (選填): Top N，預設 10
county (選填): 縣市篩選

範例：

/api/v1/ranking?start=2025-10-20&end=2025-10-30&top=50&api_key=demo-key-12345

📝 完整使用範例

JavaScript (Fetch):

fetch('http://YOUR_SERVER_IP:5000/api/v1/ranking?start=2025-10-20&end=2025-10-30&top=10&api_key=demo-key-12345')
  .then(r => r.json())
  .then(data => console.log(data));

Python (requests):

import requests
url = 'http://YOUR_SERVER_IP:5000/api/v1/ranking'
params = {
    'start': '2025-10-20',
    'end': '2025-10-30',
    'top': 10,
    'api_key': 'demo-key-12345'
}
response = requests.get(url, params=params)
print(response.json())