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:

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:

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:

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.