查询天气

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：

对于 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 的请求选项：

Pro 选项

两个选项均选择 Maps Grounding Pro SKU。如果响应中返回了任一选项，则系统会根据 Pro SKU 对请求进行结算。如需了解多功能结算规则，请参阅结算和配额。下表介绍了 Pro 选项：

所有其他 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 共享。如需了解价格，请参阅主价格表和印度价格表。