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](https://developers.google.com/maps/billing-and-pricing/sku-details/places.md.txt#grounding-lite-ess-sku).
[Pro](https://developers.google.com/maps/ai/maps-experience-agent-tools.md.txt#essentials-and-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](https://developers.google.com/maps/ai/maps-experience-agent-tools/reference/mcp/lookup_weather.md.txt)
and the
[`lookupWeather` REST reference](https://developers.google.com/maps/ai/maps-experience-agent-tools/reference/rest/v1/TopLevel/lookupWeather.md.txt).

## 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](https://developers.google.com/maps/ai/maps-experience-agent-tools.md.txt#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](https://developers.google.com/maps/billing-and-pricing/sku-details/places.md.txt#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](https://developers.google.com/maps/ai/maps-experience-agent-tools/lookup-weather.md.txt#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:

```json
{
  "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:

```bash
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.

> [!NOTE]
> **Note:** For backward compatibility, legacy requests that omit `capabilities`, `weather_options`, `air_quality_options`, and `language_code` return the flat top-level weather fields on `LookupWeatherResponse` instead of the `weather` container.

### 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](https://developers.google.com/maps/ai/maps-experience-agent-tools/reference/mcp/lookup_weather.md.txt).

## 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](https://developers.google.com/maps/billing-and-pricing/sku-details/places.md.txt#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](https://developers.google.com/maps/billing-and-pricing/sku-details/places.md.txt#grounding-lite-ess-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](https://developers.google.com/maps/billing-and-pricing/pricing.md.txt#places-pricing) and the
[India pricing table](https://developers.google.com/maps/billing-and-pricing/pricing-india.md.txt#places-pricing).