查询天气

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 天的每日天气预报	基本功能版
`AIR_QUALITY`	当前每小时空气质量	如果设置了 `date` 和 `hour`，则最长可追溯到过去 720 小时（30 天）内的单个小时；如果仅设置了 `date`，则最长可追溯到今天之前的 29 天（最多 24 个小时条目）	如果同时设置了 `date` 和 `hour`，则最长可设置为未来 96 小时（4 天）内的单个小时；如果仅设置了 `date`，则最长可设置为从今天到今天之后的 3 天（最多 24 个小时条目）	当前、今天全天和预报的基本信息。Pro：在回答中返回今天之前的`date`或过去的`hour`
`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 选项	适用情形
`POLLEN`（`capabilities`）	用户询问花粉水平、季节性过敏、树木、草或杂草花粉，或特定致敏植物种类。
`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 时区标识符，例如 "America/Los_Angeles" 或 "Asia/Tokyo"。
weather：在请求 WEATHER 时填充：
- dateTime（对于当前和每小时查询），作为世界协调时间 (UTC) 时间戳，或 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 共享。如需了解价格，请参阅主价格表和印度价格表。