Use more Maps Experience agent tools capabilities with the Pro SKU! Learn about Pro

Lookup weather

The lookup_weather tool lets an LLM retrieve environmental conditions for a location: weather, air quality, and pollen. A single request can query one, two, or all three environmental capabilities for a place ID, address, or latitude/longitude coordinates.

Requests that query only weather or current and forecast air quality are billed under the Maps Grounding Essentials SKU. Pro adds daily pollen forecasts and historical air quality up to 30 days in the past.

You can call lookup_weather through the MCP server or as the lookupWeather REST method. This page describes the environmental capabilities, request options, Pro options, response structure, and billing rules. For the full schemas, see the lookup_weather MCP reference and the lookupWeather REST reference.

Capabilities and time horizons

Use the capabilities array to select which environmental domains to return (WEATHER, AIR_QUALITY, POLLEN). capabilities is required whenever you set weather_options, air_quality_options, or language_code. If you omit capabilities, weather_options, air_quality_options, and language_code, lookup_weather runs in legacy weather mode and returns flat top-level weather fields.

All date and hour values are evaluated in the local time zone of the requested location. The following table summarizes the supported time ranges and SKU for each capability:

Capability	Current conditions (`date` and `hour` omitted)	Past conditions	Forecast conditions	SKU
`WEATHER`	Current weather	Up to 24 hours in the past (requires both `date` and `hour`; past `date` without `hour` isn't supported)	Hourly forecast up to 240 hours (10 days) when `hour` is set, or daily forecast up to 10 days when only `date` is set	Essentials
`AIR_QUALITY`	Current hourly air quality	Up to 720 hours (30 days) in the past for a single hour when `date` and `hour` are set, or up to 29 days before today (up to 24 hourly entries) when only `date` is set	Up to 96 hours (4 days) in the future for a single hour when `date` and `hour` are set, or today through 3 days after today (up to 24 hourly entries) when only `date` is set	Essentials for current, today's full day, and forecast. Pro for a `date` before today or a past `hour` when returned in the response
`POLLEN`	Current day's daily pollen forecast	Not supported (returns an `INVALID_ARGUMENT` error)	Daily pollen forecast up to 4 days after today, for 5 days including today (`hour` is ignored for pollen)	Pro when returned in the response

For AIR_QUALITY, the 720-hour past to 96-hour forecast window is anchored to the current hour. Full-day requests (date without hour) cover 00:00 to 23:00 local time and must fit inside that window—in practice from 29 days before today through three days after today.

When a request includes multiple capabilities, each capability's time horizon is evaluated independently. If the requested date and hour are within range for at least one requested capability, the response returns the supported capability containers and omits any capability whose time range isn't supported. For example, requesting AIR_QUALITY and POLLEN for a past date within 30 days returns airQuality and omits pollen. The request returns an INVALID_ARGUMENT error if the date or hour is outside the supported range of every requested capability.

Request options

The LLM sets these options when it calls the tool, based on the user's request and the tool description. You can influence which options the model uses with your own instructions; see Control Pro usage.

The following table describes the request options for lookup_weather:

Option	Description
`location`	Required. The location to query, specified as an `address` (a human-readable address, city, or landmark name), a `place_id`, or `lat_lng` (`latitude` and `longitude`).
`capabilities`	Optional. One or more values from `WEATHER`, `AIR_QUALITY`, and `POLLEN`. Duplicate values are deduplicated. Required when setting `weather_options`, `air_quality_options`, or `language_code`. When `capabilities` and those options are all omitted, returns the legacy flat-field weather response.
`date`	Optional. The local civil date (`year`, `month`, `day`) at the requested location. Omit `date` and `hour` for current conditions.
`hour`	Optional. The local hour (`0` to `23`) at the requested location. Requires `date` to be set. Setting `hour` without `date` returns an `INVALID_ARGUMENT` error.
`language_code`	Optional. The BCP-47 language code for localized text in the response, such as `en`, `ja`, or `fr-CA`. Defaults to `en`.
`weather_options.units_system`	Optional. The unit system for weather values: `METRIC` (default; Celsius, kilometers per hour, millimeters) or `IMPERIAL` (Fahrenheit, miles per hour, inches). Ignored if `WEATHER` isn't requested.
`air_quality_options.include_pollutant_concentration`	Optional. When `true`, `airQuality.hourlyResults[].pollutants[]` includes measured pollutant concentrations, emission sources, and health effects. Defaults to `false`. Ignored if `AIR_QUALITY` isn't requested.
`air_quality_options.index_region_code`	Optional. Two-letter ISO 3166-1 alpha-2 country or region code—for example, `US`, `FR`, or `CN`—used to select a local Air Quality Index (AQI) scale alongside the Universal AQI (UAQI). Defaults to the region of the requested location. Ignored if `AIR_QUALITY` isn't requested.

Pro options

Two options select the Maps Grounding Pro SKU. A request is billed under the Pro SKU when either option is returned in the response. For multi-capability billing rules, see Billing and quotas. The following table describes the Pro options:

Pro option	When to use it
`POLLEN` in `capabilities`	The user asks about pollen levels, seasonal allergies, tree, grass, or weed pollen, or specific allergenic plant species.
`AIR_QUALITY` in `capabilities` with a `date` before today or a past `hour`	The user asks about historical air quality, smoke, or pollution over the past 30 days in the location's time zone.

All other lookup_weather requests are billed under the Essentials SKU, including:

All WEATHER requests (current, 24-hour history, and 10-day hourly or daily forecasts).
Current, full-day today (date set to today without hour), and forecast AIR_QUALITY requests, including requests that set include_pollutant_concentration to true or specify index_region_code.

Example

The following MCP request asks for current weather, air quality (with pollutant concentrations), and today's pollen forecast in Tokyo. Because capabilities includes POLLEN, the request is billed under the 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
}

The following example sends the same request to the lookupWeather REST method:

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"

Replace API_KEY with your API key.

Response

When a request specifies capabilities, the response populates domain-specific containers for each requested capability alongside location metadata:

returnedLocation: The resolved location (address, placeId, or latLng, matching the input location type) for the environmental data.
timeZone: The resolved IANA time zone identifier for the location, such as "America/Los_Angeles" or "Asia/Tokyo".
weather: Populated when WEATHER is requested:
- dateTime (for current and hourly queries), as a UTC timestamp, or date (for daily forecast queries). To show local times, convert dateTime with the timeZone field.
- Temperature (temperature, feelsLikeTemperature, heatIndex, or daily maxTemperature, minTemperature, feelsLikeMaxTemperature, feelsLikeMinTemperature, maxHeatIndex).
- weatherCondition, precipitation, wind, airPressure, relativeHumidity, uvIndex, thunderstormProbability, cloudCover, and daily sunEvents and moonEvents. Sunrise, sunset, moonrise, and moonset times are UTC timestamps.
- attribution: The attribution that you must show with the weather data.
airQuality: Populated when AIR_QUALITY is requested:
- hourlyResults[]: Contains one entry for current or single-hour queries, or up to 24 entries covering the full local day (00:00 to 23:00) when only date is set. When date is today and hour is omitted, the entries combine the earlier historical hours of today, the current hour, and the remaining forecast hours. Each entry includes:
  - dateTime: The local civil date and time (year, month, day, hours, minutes, seconds, and utcOffset) in the location's time zone.
  - indexes[]: Universal AQI and, when available, the local AQI (displayName, value, valueDisplay, category, and dominantPollutant).
  - pollutants[]: Populated when include_pollutant_concentration is true (displayName, fullName, concentration in ppb or µg/m³, and additionalInfo with emission sources and health effects).
  - healthRecommendations: Guidance for generalPopulation, elderly, lungDiseasePopulation, heartDiseasePopulation, athletes, pregnantWomen, and children.
- attribution: The attribution that you must show with the air quality data.
pollen: Populated when POLLEN is requested:
- dailyForecast: The pollen forecast for the requested date:
  - date: The civil calendar date of the forecast.
  - categories[]: Broad allergen categories (Tree, Grass, and Weed), each with displayName, inSeason, Universal Pollen Index index (0 to 5 scale, category, and description), and healthRecommendations[].
  - plantSpecies[]: Specific allergenic plant species (such as Birch, Ragweed, or Japanese Cedar), each with code, displayName, botanical family, inSeason, Universal Pollen Index index, typical blooming season, and crossReactions.
- attribution: The attribution that you must show with the pollen data.

Partial availability across capabilities

When a request includes multiple capabilities, each capability is evaluated and fetched independently. If one capability is unavailable for the requested location, outside its supported time range, or fails transiently while at least one other capability succeeds, the response returns the available capability containers and omits the unavailable or failed container. The request fails with an error only if every requested capability fails.

For full field details, see the lookup_weather reference.

Billing and quotas

Each lookup_weather request is one billable event, even when capabilities requests two or three environmental domains in the same call:

A request is billed under the highest SKU tier among the capabilities that succeed and are returned in the response:
- If the response includes pollen or historical airQuality (a date before today or a past hour in the location's time zone), the request is billed under the Maps Grounding Pro SKU. Requesting both POLLEN and historical AIR_QUALITY in one call still counts as one Pro billable event.
- Otherwise, the request is billed under the Maps Grounding Essentials SKU.
If a Pro capability is omitted in a multi-capability request—because it's unavailable for the location, outside its supported time range, or fails transiently—and only Essentials capabilities are returned in the response, the request is billed under the Essentials SKU.

The lookup_weather quota is 300 queries per minute for each project, shared by both SKUs. For pricing, see the Main pricing table and the India pricing table.