Weather MCP

# Open-Meteo API 使用指南 本文件說明如何使用 Open-Meteo API 查詢天氣資料，包含預測、歷史資料與時區處理。 --- ## 目錄 1. [API 端點概覽](#api-端點概覽) 2. [預測 API (Forecast)](#預測-api-forecast) 3. [歷史 API (Archive)](#歷史-api-archive) 4. [時區處理](#時區處理) 5. [實用範例](#實用範例) --- ## API 端點概覽 | API 類型 | 端點 | 用途 | 時間範圍 | |---------|------|------|---------| | 預測 API | `https://api.open-meteo.com/v1/forecast` | 未來天氣預測 + 近期歷史 | 過去 92 天 ~ 未來 16 天 | | 歷史 API | `https://archive-api.open-meteo.com/v1/archive` | 長期歷史資料 | 1940 年 ~ 現在 -5 天 | --- ## 預測 API (Forecast) ### 基本 URL 結構 ``` https://api.open-meteo.com/v1/forecast?latitude={lat}&longitude={lon}&hourly={variables}&timezone=auto ``` ### 核心參數 #### 必要參數 - `latitude`: 緯度 (例如：35.6762) - `longitude`: 經度 (例如：139.6503) #### 資料類型參數 **逐小時資料 (`hourly`)** ``` &hourly=temperature_2m,relative_humidity_2m,precipitation_probability,wind_speed_10m ``` 常用變數： - `temperature_2m`: 地表 2 公尺溫度 (°C) - `relative_humidity_2m`: 相對濕度 (%) - `precipitation_probability`: 降雨機率 (%) - `wind_speed_10m`: 地表 10 公尺風速 (km/h) - `precipitation`: 降雨量 (mm) **每日摘要 (`daily`)** ``` &daily=temperature_2m_max,temperature_2m_min,precipitation_sum ``` 常用變數： - `temperature_2m_max`: 每日最高溫 - `temperature_2m_min`: 每日最低溫 - `precipitation_sum`: 每日總降雨量 - `precipitation_probability_max`: 每日最高降雨機率 #### 時間範圍參數 **查詢未來天氣** ``` &forecast_days=7 ``` - 範圍：1-16 天 - 預設：7 天 **查詢過去天氣** ⭐ 重要 ``` &past_days=1 ``` - 範圍：0-92 天 - 可查詢**昨天**的實測資料 - 比歷史 API 更方便（無 5 天延遲） **指定日期範圍** ``` &start_date=2025-10-03&end_date=2025-10-05 ``` - 格式：`YYYY-MM-DD` - 可精確指定查詢區間 #### 時區參數 ``` &timezone=auto ``` - 自動根據經緯度判斷時區 - 回傳時間使用當地時間而非 UTC --- ## 實用範例 ### 1. 查詢當前天氣（未來 12 小時） ``` https://api.open-meteo.com/v1/forecast?latitude=25.033&longitude=121.5654&hourly=temperature_2m,relative_humidity_2m,precipitation_probability,wind_speed_10m&forecast_days=1&timezone=auto ``` ### 2. 查詢昨天的天氣 ⭐ ``` https://api.open-meteo.com/v1/forecast?latitude=25.033&longitude=121.5654&hourly=temperature_2m,relative_humidity_2m,precipitation&past_days=1&forecast_days=0&timezone=auto ``` **Python 實作** ```python from datetime import datetime, timedelta yesterday = (datetime.now() - timedelta(days=1)).strftime('%Y-%m-%d') url = ( "https://api.open-meteo.com/v1/forecast" f"?latitude={lat}&longitude={lon}" "&hourly=temperature_2m,relative_humidity_2m,precipitation" "&past_days=1" "&forecast_days=0" "&timezone=auto" ) ``` ### 3. 查詢明天的天氣 **方法 A：使用 forecast_days** ``` https://api.open-meteo.com/v1/forecast?latitude=25.033&longitude=121.5654&hourly=temperature_2m&forecast_days=2&timezone=auto ``` 回傳今天 + 明天共 48 小時，程式中再篩選明天的部分。 **方法 B：使用 start_date/end_date（精確）** ```python from datetime import datetime, timedelta tomorrow = (datetime.now() + timedelta(days=1)).strftime('%Y-%m-%d') url = ( "https://api.open-meteo.com/v1/forecast" f"?latitude={lat}&longitude={lon}" f"&start_date={tomorrow}&end_date={tomorrow}" "&hourly=temperature_2m,relative_humidity_2m,precipitation_probability,wind_speed_10m" "&timezone=auto" ) ``` ### 4. 查詢未來 7 天每日摘要 ``` https://api.open-meteo.com/v1/forecast?latitude=25.033&longitude=121.5654&daily=temperature_2m_max,temperature_2m_min,precipitation_sum,precipitation_probability_max&forecast_days=7&timezone=auto ``` **回傳格式** ```json { "daily": { "time": ["2025-10-02", "2025-10-03", "2025-10-04", ...], "temperature_2m_max": [28.5, 29.1, 27.8, ...], "temperature_2m_min": [22.3, 23.0, 21.5, ...], "precipitation_sum": [0.0, 5.2, 0.0, ...], "precipitation_probability_max": [30, 60, 20, ...] } } ``` ### 5. 查詢連續時間線（過去 + 現在 + 未來） ``` https://api.open-meteo.com/v1/forecast?latitude=25.033&longitude=121.5654&hourly=temperature_2m&past_days=3&forecast_days=7&timezone=auto ``` 回傳：過去 3 天 + 未來 7 天的連續資料（共 240 小時） --- ## 歷史 API (Archive) ### 何時使用歷史 API？ - 查詢 **92 天以前**的資料 - 需要 **1940 年起**的長期歷史資料 - 研究氣候變遷、統計分析 ⚠️ **限制**：資料有 5 天延遲（例如：10/2 查詢最新資料只到 9/27） ### 基本 URL 結構 ``` https://archive-api.open-meteo.com/v1/archive?latitude={lat}&longitude={lon}&start_date={start}&end_date={end}&hourly={variables}&timezone=auto ``` ### 必要參數 - `start_date`: 起始日期（格式：`YYYY-MM-DD`）⚠️ 必填 - `end_date`: 結束日期（格式：`YYYY-MM-DD`）⚠️ 必填 ### 範例：查詢上個月的天氣 ```python import requests from datetime import datetime, timedelta # 計算上個月日期範圍 today = datetime.now() last_month_end = today.replace(day=1) - timedelta(days=1) last_month_start = last_month_end.replace(day=1) url = ( "https://archive-api.open-meteo.com/v1/archive" f"?latitude=35.6762&longitude=139.6503" f"&start_date={last_month_start.strftime('%Y-%m-%d')}" f"&end_date={last_month_end.strftime('%Y-%m-%d')}" "&hourly=temperature_2m,relative_humidity_2m,precipitation" "&timezone=auto" ) response = requests.get(url, timeout=15) data = response.json() ``` --- ## 時區處理 ### `timezone=auto` 的作用 自動根據經緯度判斷時區，回傳的時間戳使用**當地時間**。 #### 範例 **東京** (UTC+9) ```json { "timezone": "Asia/Tokyo", "hourly": { "time": ["2025-10-02T00:00", "2025-10-02T01:00", ...] } } ``` → 時間戳代表**東京當地時間** 0 點、1 點... **台北** (UTC+8) ```json { "timezone": "Asia/Taipei", "hourly": { "time": ["2025-10-02T00:00", "2025-10-02T01:00", ...] } } ``` → 時間戳代表**台北當地時間** 0 點、1 點... **倫敦** (UTC+0/+1) ```json { "timezone": "Europe/London", "hourly": { "time": ["2025-10-02T00:00", "2025-10-02T01:00", ...] } } ``` → 時間戳代表**倫敦當地時間** 0 點、1 點... ### 為什麼要使用 `timezone=auto`？ ✅ 使用者不需手動轉換時區 ✅ 時間資料直覺易懂（顯示當地時間） ✅ 避免 UTC 與當地時間混淆 --- ## API 選擇決策樹 ``` 需要查詢天氣資料 │ ├─ 查詢昨天/最近 3 個月？ │ └─ 使用 Forecast API + past_days 參數 │ ├─ 查詢明天/未來 16 天？ │ └─ 使用 Forecast API + forecast_days 或 start_date/end_date │ ├─ 查詢 3 個月～5 天前的資料？ │ └─ 使用 Archive API │ └─ 查詢長期歷史（如：去年、10 年前）？ └─ 使用 Archive API ``` --- ## 完整 Python 範例 ### 查詢昨天、今天、明天的天氣 ```python import requests from datetime import datetime, timedelta def get_weather_timeline(lat, lon, past_days=1, forecast_days=1): """ 查詢連續時間線的天氣資料 Args: lat: 緯度 lon: 經度 past_days: 過去天數（0-92） forecast_days: 未來天數（1-16） """ url = ( "https://api.open-meteo.com/v1/forecast" f"?latitude={lat}&longitude={lon}" "&hourly=temperature_2m,relative_humidity_2m,precipitation_probability,wind_speed_10m" f"&past_days={past_days}" f"&forecast_days={forecast_days}" "&timezone=auto" ) response = requests.get(url, timeout=15) response.raise_for_status() return response.json() # 查詢昨天 + 今天 + 明天 data = get_weather_timeline(25.033, 121.5654, past_days=1, forecast_days=1) print(f"時區: {data['timezone']}") print(f"時間範圍: {data['hourly']['time'][0]} ~ {data['hourly']['time'][-1]}") print(f"資料點數: {len(data['hourly']['time'])} 小時") ``` --- ## 參考資源 - [Open-Meteo 官方文件](https://open-meteo.com/en/docs) - [Forecast API 文件](https://open-meteo.com/en/docs) - [Archive API 文件](https://open-meteo.com/en/docs/historical-weather-api) --- **最後更新**: 2025-10-02