查詢天氣

lookup_weather 工具可讓 LLM 擷取某個地點的環境條件，包括天氣、空氣品質和花粉。單一要求可查詢地點 ID、地址或經緯度座標的一、二或全部三種環境功能。

如果要求只查詢天氣，或目前和預測的空氣品質，則會依 Maps Grounding Essentials SKU 計費。Pro 則會新增每日花粉預測，以及過去最多 30 天的空氣品質記錄。

您可以透過 MCP 伺服器或 lookupWeather REST 方法呼叫 lookup_weather。本頁說明環境功能、要求選項、Pro 選項、回應結構和計費規則。如需完整結構定義，請參閱 lookup_weather MCP 參考資料和 lookupWeather REST 參考資料。

功能和時間範圍

使用 capabilities 陣列選取要傳回的環境網域 (WEATHER、AIR_QUALITY、POLLEN)。每當您設定 weather_options、air_quality_options 或 language_code 時，都必須設定 capabilities。如果省略 capabilities、weather_options、air_quality_options 和 language_code，lookup_weather 會在舊版天氣模式下執行，並傳回扁平的頂層天氣欄位。

所有 date 和 hour 值都會根據所要求位置的當地時區進行評估。下表摘要說明各項功能支援的日期範圍和 SKU：

功能	目前天氣狀況 (省略 `date` 和 `hour`)	過往狀況	預測條件	SKU
`WEATHER`	目前天氣	過去 24 小時內 (必須同時提供 `date` 和 `hour`；不支援只提供過去 `date` 而未提供 `hour`)	設定 `hour` 時，可取得最多 240 小時 (10 天) 的每小時預報；僅設定 `date` 時，可取得最多 10 天的每日預報	Essentials
`AIR_QUALITY`	目前每小時空氣品質	如果同時設定 `date` 和 `hour`，則最多可回溯至 720 小時 (30 天) 前的單一小時；如果只設定 `date`，則最多可回溯至 29 天前 (最多 24 個小時項目)	如果設定 `date` 和 `hour`，則最多可設定未來 96 小時 (4 天) 內的單一小時；如果只設定 `date`，則可設定今天到未來 3 天 (最多 24 個小時項目)	目前、今天全天和預測的基本資訊。如果回應傳回今天之前的 `date` 或過去的 `hour`，則為 Pro
`POLLEN`	當日花粉預測	不支援 (傳回 `INVALID_ARGUMENT` 錯誤)	每日花粉預測，最多可預測今天之後 4 天，共 5 天 (包括今天) (花粉會忽略 `hour`)	Pro (在回應中傳回時)

AIR_QUALITY 的 720 小時過去至 96 小時預測時間範圍，是以目前小時為基準。全天要求 (date，不含 hour) 涵蓋當地時間 00:00 至 23:00，且必須符合該時間範圍，實際上是從今天前 29 天到今天後 3 天。

如果要求包含多項功能，系統會獨立評估每項功能的時間範圍。如果要求的 date 和 hour 在至少一項要求的功能範圍內，回應會傳回支援的功能容器，並省略不支援日期範圍的功能。舉例來說，如果要求 30 天內過去日期的 AIR_QUALITY 和 POLLEN，系統會傳回 airQuality 並省略 pollen。如果 date 或 hour 超出每項要求功能的支援範圍，要求會傳回 INVALID_ARGUMENT 錯誤。

要求選項

LLM 呼叫工具時，會根據使用者要求和工具說明設定這些選項。您可以透過自己的指令，影響模型使用的選項；請參閱「控管 Pro 用量」。

下表說明 lookup_weather 的要求選項：

選項	說明
`location`	必填。要查詢的位置，指定為 `address` (人類可讀的地址、城市或地標名稱)、`place_id` 或 `lat_lng` (`latitude` 和 `longitude`)。
`capabilities`	(選用步驟) `WEATHER`、`AIR_QUALITY` 和 `POLLEN` 中的一或多個值。重複的值會簡化。設定 `weather_options`、`air_quality_options` 或 `language_code` 時，必須提供這個屬性。如果省略 `capabilities` 和上述所有選項，系統會傳回舊版平面欄位天氣回應。
`date`	(選用步驟) 所要求位置的當地民用日期 (`year`、`month`、`day`)。省略 `date` 和 `hour`，以取得目前天氣狀況。
`hour`	(選用步驟) 要求位置的當地時間 (`0` 至 `23`)。必須設定 `date`。如果設定 `hour` 時未指定 `date`，系統會傳回 `INVALID_ARGUMENT` 錯誤。
`language_code`	(選用步驟) 回應中本地化文字的 BCP-47 語言代碼，例如 `en`、`ja` 或 `fr-CA`。預設為 `en`。
`weather_options.units_system`	(選用步驟) 天氣值的單位系統：`METRIC` (預設；攝氏、公里/小時、公釐) 或 `IMPERIAL` (華氏、英里/小時、英寸)。如果未要求 `WEATHER`，則會略過。
`air_quality_options.include_pollutant_concentration`	(選用步驟) `true` 時，`airQuality.hourlyResults[].pollutants[]` 會提供測得的污染物濃度、排放源和健康影響。預設值為 `false`。如果未要求 `AIR_QUALITY`，則會略過。
`air_quality_options.index_region_code`	(選用步驟) 兩位字母的 ISO 3166-1 alpha-2 國家/地區或區域代碼 (例如 `US`、`FR` 或 `CN`)，用於選取當地空氣品質指數 (AQI) 級別和通用 AQI (UAQI)。預設為要求位置的區域。如果未要求 `AIR_QUALITY`，則會略過。

Pro 選項

其中兩個選項會選取 Maps Grounding Pro SKU。如果回應傳回任一選項，系統會依 Pro SKU 向您收取要求費用。如要瞭解多功能計費規則，請參閱「計費和配額」。下表說明 Pro 選項：

Pro 選項	適用時機
`capabilities`的`POLLEN`	使用者詢問花粉量、季節性過敏、樹木、草本植物或雜草花粉，或特定過敏原植物物種。
`capabilities`中的`AIR_QUALITY`，`date`在今天之前或過去的`hour`	使用者詢問過去 30 天內，某地點時區的空氣品質、煙霧或汙染歷史記錄。

所有其他 lookup_weather 要求都會依 Essentials SKU 計費，包括：

所有 WEATHER 要求 (目前、24 小時記錄，以及 10 天每小時或每日預測)。
目前、今天全天 (date 設為今天，不含 hour) 和預測 AIR_QUALITY 要求，包括將 include_pollutant_concentration 設為 true 或指定 index_region_code 的要求。

範例

下列 MCP 要求會詢問東京目前的天氣、空氣品質 (含污染物濃度) 和今日花粉預報。由於 capabilities 包含 POLLEN，因此系統會以 Pro SKU 計費：

{
  "method": "tools/call",
  "params": {
    "name": "lookup_weather",
    "arguments": {
      "location": {"address": "Tokyo, Japan"},
      "capabilities": ["WEATHER", "AIR_QUALITY", "POLLEN"],
      "weather_options": {
        "units_system": "METRIC"
      },
      "air_quality_options": {
        "include_pollutant_concentration": true
      },
      "language_code": "en"
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}

下列範例會將相同要求傳送至 lookupWeather REST 方法：

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-d '{
  "location": {"address": "Tokyo, Japan"},
  "capabilities": ["WEATHER", "AIR_QUALITY", "POLLEN"],
  "weatherOptions": {"unitsSystem": "METRIC"},
  "airQualityOptions": {"includePollutantConcentration": true},
  "languageCode": "en"
}' \
"https://mapstools.googleapis.com/v1:lookupWeather"

將 API_KEY 替換為您的 API 金鑰。

回應

如果要求指定 capabilities，回應會為每項要求的功能填入網域專屬容器，以及地點中繼資料：

returnedLocation：環境資料的解析位置 (address、placeId 或 latLng，與輸入 location 類型相符)。
timeZone：位置的解析 IANA 時區 ID，例如 "America/Los_Angeles" 或 "Asia/Tokyo"。
weather：要求 WEATHER 時填入：
- dateTime (用於目前和每小時查詢)，以世界標準時間戳記表示，或 date (用於每日預測查詢)。如要顯示當地時間，請使用 timeZone 欄位轉換 dateTime。
- 溫度 (temperature、feelsLikeTemperature、heatIndex，或每日 maxTemperature、minTemperature、feelsLikeMaxTemperature、feelsLikeMinTemperature、maxHeatIndex)。
- weatherCondition、precipitation、wind、airPressure、relativeHumidity、uvIndex、thunderstormProbability、cloudCover，以及每日sunEvents和moonEvents。日出、日落、月出和月落時間均為世界標準時間 (UTC) 時間戳記。
- attribution：必須與天氣資料一併顯示的出處資訊。
airQuality：要求 AIR_QUALITY 時填入：
- hourlyResults[]：包含目前或單一小時查詢的一個項目，或最多 24 個項目，涵蓋整個當地日期 (00:00 至 23:00)，前提是只設定 date。如果 date 是今天，且省略 hour，則項目會結合今天稍早的歷來小時、目前小時和剩餘的預測小時。每個項目都包含：
  - dateTime：地點時區的當地民用日期和時間 (year、month、day、hours、minutes、seconds 和 utcOffset)。
  - indexes[]：通用 AQI，以及當地 AQI (如有) (displayName、value、valueDisplay、category 和 dominantPollutant)。
  - pollutants[]：當 include_pollutant_concentration 為 true 時填入 (ppb 或 µg/m³ 中的 displayName、fullName、concentration，以及排放量為 sources 且健康狀況為 effects 的 additionalInfo)。
  - healthRecommendations：generalPopulation、elderly、lungDiseasePopulation、heartDiseasePopulation、athletes、pregnantWomen 和 children 的指南。
- attribution：顯示空氣品質資料時，必須一併顯示的作者資訊。
pollen：要求 POLLEN 時填入：
- dailyForecast：所要求 date 的花粉預測：
  - date：預測的國曆日期。
  - categories[]：廣泛的過敏原類別 (Tree、Grass 和 Weed)，每個類別都有 displayName、inSeason、通用花粉指數 index (0 至 5 級、category 和 description) 和 healthRecommendations[]。
  - plantSpecies[]：特定致敏植物物種 (例如樺樹、豬草或日本柳杉)，每種植物都有 code、displayName、植物學 family、inSeason、通用花粉指數 index、典型花期 season 和 crossReactions。
- attribution：必須與花粉資料一併顯示的出處資訊。

部分功能僅在特定地區提供

如果要求包含多項功能，系統會分別評估及擷取每項功能。如果某項功能在要求的位置無法使用、超出支援的日期範圍，或暫時失敗，但至少有一項其他功能成功，回應會傳回可用的功能容器，並省略無法使用或失敗的容器。只有在所有要求的功能都失敗時，要求才會失敗並傳回錯誤。

如需完整的欄位詳細資料，請參閱 lookup_weather 參考資料。

計費和配額

每個 lookup_weather 要求都是一個計費事件，即使 capabilities 在同一個呼叫中要求兩個或三個環境網域也一樣：

系統會根據成功執行並在回應中傳回的功能，以最高 SKU 級別計費：
- 如果回覆包含 pollen 或歷來 airQuality (今天之前的 date，或該地點時區的過去 hour)，則會依 Maps Grounding Pro SKU 計費。在一次呼叫中同時要求 POLLEN 和歷來 AIR_QUALITY，仍算是一次 Pro 計費事件。
- 否則，系統會依 Maps Grounding Essentials SKU 計費。
如果多功能要求中省略了 Pro 功能 (因為該功能不適用於該位置、超出支援的日期範圍，或暫時失敗)，且回應中僅傳回 Essentials 功能，則該要求會依 Essentials SKU 計費。

lookup_weather 配額為每項專案每分鐘 300 次查詢，由兩個 SKU 共用。如需定價資訊，請參閱主要價目表和印度價目表。