lookup_weather
Retrieves comprehensive environmental intelligence for a location, including Weather, Air Quality (AQI & pollutants), and Pollen (tree, grass, weed, and plant species allergen levels): current conditions, hourly forecasts/history, and daily forecasts for Weather and Air Quality; Pollen is a daily forecast only (today through +4 days, no hourly or past data).
**Available Environmental Domains & Capabilities (`capabilities`: `WEATHER`, `AIR_QUALITY`, `POLLEN` — CRITICAL):**
* **Mandatory Explicit Selection:** You **MUST** include at least one of `WEATHER`, `AIR_QUALITY`, or `POLLEN` in `capabilities` on every call. Omitting `capabilities` is **NOT allowed**.
* **Broad / Ambiguous Outdoor Queries (Full Ambient Outdoor Suite):** If the user asks a general outdoor, travel, or situational question without restricting to a specific domain (e.g., "What are outdoor conditions like right now for a run?"), **explicitly include all three capabilities** (`capabilities: ["WEATHER", "AIR_QUALITY", "POLLEN"]`) to return the complete ambient outdoor suite (Weather + Air Quality + Pollen); for a past `date`/`hour`, leave out `POLLEN`, which has no history.
* **Targeted Domain Selection (Specific Queries):** If the user asks specifically for only one or two domains (e.g., "What is the AQI in Seattle right now?"), include **only** the requested capabilities (`WEATHER`, `AIR_QUALITY`, and/or `POLLEN`). Only the requested domain(s) will be executed and returned.
**Specific Data Available by Domain:**
* **Weather (`weather`):** Temperature (Current, Feels Like, Max/Min, Heat Index), Wind (Speed, Gusts, Direction), Celestial Events (Sunrise/Sunset, Moon Phase), Precipitation (Type, Probability, Quantity/QPF), and Atmospheric Conditions (UV Index, Humidity, Cloud Cover, Thunderstorm Probability, Air Pressure).
* **Air Quality (`air_quality`):** Universal & Local Air Quality Indexes (AQI value, category, dominant pollutant), Health Recommendations across 7 sensitivity groups, and Pollutant Concentrations (`include_pollutant_concentration: true`). Each index has its own dominant pollutant; report it per index (e.g., don't give the Universal AQI's pollutant for the US AQI).
* **Pollen (`pollen`):** Daily Universal Pollen Index (UPI, 0–5) per Tree, Grass, and Weed category and per plant species (`index.value` with its `index.category`, e.g. 1 = "Very Low"), in-season status, cross-reactions, and health recommendations.
* **Missing Pollen Fields:** a missing `in_season` means not in season. Leave out plant species returned without an `index`, unless the user asks about that plant; then say no pollen data is reported for it today (don't infer a level).
**Location Rules (CRITICAL):**
The target location MUST be specified in `location` using **ONLY ONE** of the following `oneof` sub-fields:
1. **Geographic Coordinates (`lat_lng`):**
* Use when exact latitude/longitude coordinates are known.
* Example: `{"location": {"lat_lng": {"latitude": 34.0522, "longitude": -118.2437}}}`
2. **Place ID (`place_id`):**
* An unambiguous Google Maps Place ID (e.g., obtained from `search_places` or `resolve_names`).
* Example: `{"location": {"place_id": "ChIJLU7jZClu5kcR4PcOOO6p3I0"}}`
3. **Address String (`address`):**
* A city/region, neighborhood, landmark or point of interest, street address, or postal code, ideally with the city/country.
* Example: `{"location": {"address": "Paris, France"}}`
**Time & Usage Modes (`date` and `hour` — CRITICAL):**
* **Local Timezone Reference:** All `date` (`{year, month, day}`) and `hour` (`0-23`) inputs MUST be expressed in the **requested `location`'s local civil time zone** (e.g., a query for `"Paris tomorrow at 13:00"` uses `Europe/Paris` local date and hour `13`), never UTC or the caller's time zone.
* **1. Current Conditions (`date` omitted AND `hour` omitted):**
* Provide `location` and the target `capabilities` (`WEATHER`, `AIR_QUALITY`, `POLLEN`). Do **NOT** specify `date` or `hour`.
* Returns real-time Current Conditions (`CC`) for the requested domain(s) (current Weather, current-hour Air Quality, and/or today's Pollen forecast).
* For **Air Quality**, Current Conditions is a **single hour**: do **NOT** use it alone to answer air quality or broad outdoor questions about **today** as a whole (use Daily Queries below).
* **2. Hourly Forecast / History (`date` specified AND `hour` specified `0-23`):**
* Provide `location`, `date` (`{year, month, day}`), `hour` (`0-23`), and the target `capabilities`. If minutes are mentioned, round down to the nearest hour.
* **CRITICAL CONSTRAINT (`date` is REQUIRED when `hour` is set):** Providing `hour` without `date` (`date` omitted, `hour` set) is **NOT allowed** and will fail with an error. Even when the user asks about a specific hour **today** (e.g., `"at 13:00 today"`), you **MUST** populate both `date` (today's date at `location`) and `hour`.
* Executes an hourly lookup for requested Weather and/or Air Quality at `YYYY-MM-DD-HH` and a daily lookup for requested Pollen on `YYYY-MM-DD`.
* **Weather "when" questions:** for **weather** questions asking **when / what time / best time** (e.g., `"what time will it stop raining?"`), use hourly `WEATHER` calls (`date` + `hour`) for the relevant hours. A daily Weather forecast has no hourly values. For **broad outdoor** "when / best time" questions (e.g., `"when is the best time to go walking today?"`), make these hourly `WEATHER` calls in addition to the full-day call for Air Quality (and Pollen) described under Daily Queries.
* **3. Daily Queries (`date` specified AND `hour` omitted):**
* Provide `location`, `date` (`{year, month, day}` in the requested `location`'s local civil time) without `hour`, and the target `capabilities` for full-day queries (e.g., `"weather and pollen in London tomorrow"`).
* **Air Quality and broad outdoor questions about today:** for **air quality** questions and **broad outdoor** questions (which include Air Quality) about **today** (e.g., `"how will the air quality change today"`, `"is today a good day for a picnic?"`), set `date` to **today's date at `location`** (hour omitted) to get the day's hourly Air Quality series. A Current Conditions call alone returns only the current hour of Air Quality and is not enough; you may add one if the user also asks about "now".
* **Air Quality time windows:** for an air quality question about a window within one day (e.g., `"air quality between noon and 6 PM"`), prefer **one Daily call** for that date and read the window's hours from the Air Quality series, rather than sampling individual hours. If you use hourly calls, cover **every** hour of the window.
* Returns daily forecasts for requested **Weather** and/or **Pollen**, and the day's hourly **Air Quality** series covering the full local day (00:00–23:00 local): 24 historical hours for a past date, 24 forecasted hours for a future date, and for **today** the earlier hours (history), the current hour, and the remaining hours (forecast).
**Supported Time Horizons by Domain:**
* **Weather:** Hourly from 24 hours ago up to 240 hours (10 days) ahead (past hours need both `date` and `hour`); daily up to 10 days including today (today through +9 days); no daily history.
* **Air Quality:** Hourly from 720 hours (30 days) ago up to 96 hours (4 days) ahead; a full-day call must fit inside that window (in practice today −29 days through +3 days).
* **Pollen:** Daily only, today through +4 days (5 days including today); no past dates, and `hour` is ignored.
* *(Note: If several capabilities are requested and the `date`/`hour` is outside one of their ranges, the call still succeeds and returns only the supported ones.)*
* **Out-of-range requests:** If a requested date or hour may be outside a domain's supported range above (e.g., Pollen for a past date), still call `lookup_weather` for the **requested** date/hour; the error
Schema valid · SHA-256 c0a2b145cd05…
View input schema
{
"type": "object",
"properties": {
"airQualityOptions": {
"$ref": "#/$defs/AirQualityOptions",
"description": "Optional. Options specific to air quality requests. Ignored if `AIR_QUALITY` is not requested in `capabilities`."
},
"capabilities": {
"description": "Optional. The environmental capabilities to include in the response.",
"items": {
"enum": [
"CAPABILITY_UNSPECIFIED",
"WEATHER",
"AIR_QUALITY",
"POLLEN"
],
"type": "string",
"x-google-enum-descriptions": [
"Unspecified capability.",
"Weather conditions (temperature, precipitation, wind, UV, etc.).",
"Air quality information (AQI, pollutants, and health recommendations).",
"Pollen information (tree, grass, weed, and plant species allergen levels)."
]
},
"type": "array"
},
"date": {
"$ref": "#/$defs/Date",
"description": "Optional. Specifies the date of the requested environmental information, relative to the local timezone of the location specified in the `location` field. Supported date ranges depend on the requested capabilities: - `WEATHER`: up to 24 hours in the past (when `hour` is also set) and up to 10 days (240 hours) in the future (today through +9 days for daily forecasts). - `AIR_QUALITY`: up to 30 days (720 hours) in the past and up to 4 days (96 hours) in the future. - `POLLEN`: today through +4 days (up to 5 days including today; historical dates are not supported)."
},
"hour": {
"description": "Optional. Specifies the hour of the requested environmental information, in 24-hour format (0-23), relative to the local timezone of the location specified in the `location` field. Requires `date` to be specified. Supported hourly ranges depend on the requested capabilities: - `WEATHER`: up to 24 hours in the past and up to 240 hours (10 days) in the future. - `AIR_QUALITY`: up to 30 days (720 hours) in the past and up to 4 days (96 hours) in the future. - `POLLEN`: returns daily forecasts only; `hour` is ignored for pollen.",
"format": "int32",
"type": "integer"
},
"languageCode": {
"description": "Optional. The BCP-47 language code for localized text in the response (e.g. \"en\", \"ja\", \"fr-CA\"). Defaults to \"en\" if not specified.",
"type": "string"
},
"location": {
"$ref": "#/$defs/Location",
"description": "Required. The location to get the weather conditions for."
},
"unitsSystem": {
"description": "Optional. The units system to use for the returned weather conditions. If not provided, the returned weather conditions will be in the metric system (default = METRIC).",
"enum": [
"UNITS_SYSTEM_UNSPECIFIED",
"IMPERIAL",
"METRIC"
],
"type": "string",
"x-google-enum-descriptions": [
"The units system is unspecified.",
"The imperial units system (e.g. Fahrenheit, miles, etc).",
"The metric units system (e.g. Celsius, kilometers, etc)."
]
},
"weatherOptions": {
"$ref": "#/$defs/WeatherOptions",
"description": "Optional. Options specific to weather requests. `weather_options.units_system` is supported in tandem with top-level `units_system` (tag 4) to preserve backwards compatibility for existing callers; returns INVALID_ARGUMENT if both specify conflicting unit systems. Ignored if `WEATHER` is not requested in `capabilities`."
}
},
"required": [
"location"
],
"$defs": {
"AirQualityOptions": {
"description": "Options specific to air quality requests.",
"properties": {
"includePollutantConcentration": {
"description": "Optional. If true, includes detailed pollutant concentrations and additional information (sources and effects) in the air quality response.",
"type": "boolean"
},
"indexRegionCode": {
"description": "Optional. Two-letter ISO 3166-1 alpha-2 country/region code (e.g. \"US\", \"FR\", \"CN\") used to select the preferred local Air Quality Index (AQI) scale alongside the Universal AQI (UAQI). If not specified, defaults to the region of the requested location.",
"type": "string"
}
},
"type": "object"
},
"Date": {
"description": "Represents a whole or partial calendar date, such as a birthday. The time of day and time zone are either specified elsewhere or are insignificant. The date is relative to the Gregorian Calendar. This can represent one of the following: * A full date, with non-zero year, month, and day values. * A month and day, with a zero year (for example, an anniversary). * A year on its own, with a zero month and a zero day. * A year and month, with a zero day (for example, a credit card expiration date). Related types: * google.type.TimeOfDay * google.type.DateTime * google.protobuf.Timestamp",
"properties": {
"day": {
"description": "Day of a month. Must be from 1 to 31 and valid for the year and month, or 0 to specify a year by itself or a year and month where the day isn't significant.",
"format": "int32",
"type": "integer"
},
"month": {
"description": "Month of a year. Must be from 1 to 12, or 0 to specify a year without a month and day.",
"format": "int32",
"type": "integer"
},
"year": {
"description": "Year of the date. Must be from 1 to 9999, or 0 to specify a date without a year.",
"format": "int32",
"type": "integer"
}
},
"type": "object"
},
"LatLng": {
"description": "An object that represents a latitude/longitude pair. This is expressed as a pair of doubles to represent degrees latitude and degrees longitude. Unless specified otherwise, this object must conform to the WGS84 standard <https://en.wikipedia.org/wiki/World_Geodetic_System#1984_version>. Values must be within normalized ranges.",
"properties": {
"latitude": {
"description": "The latitude in degrees. It must be in the range [-90.0, +90.0].",
"format": "double",
"type": "number"
},
"longitude": {
"description": "The longitude in degrees. It must be in the range [-180.0, +180.0].",
"format": "double",
"type": "number"
}
},
"type": "object"
},
"Location": {
"description": "Represents a location for the weather request.",
"properties": {
"address": {
"description": "Human-readable address (e.g., street address, city, or postal code). Only one of the following fields should be set: this field, latLng, placeId.",
"type": "string"
},
"latLng": {
"$ref": "#/$defs/LatLng",
"description": "A point specified using geographic coordinates. Only one of the following fields should be set: this field, placeId, address."
},
"placeId": {
"description": "The Place ID associated with the location. Only one of the following fields should be set: this field, latLng, address.",
"type": "string"
}
},
"type": "object"
},
"WeatherOptions": {
"description": "Options specific to weather requests.",
"properties": {
"unitsSystem": {
"description": "Optional. The units system to use for the returned weather conditions. If not provided, the returned weather conditions will be in the metric system (default = METRIC).",
"enum": [
"UNITS_SYSTEM_UNSPECIFIED",
"IMPERIAL",
"METRIC"
],
"type": "string",
"x-google-enum-descriptions": [
"The units system is unspecified.",
"The imperial units system (e.g. Fahrenheit, miles, etc).",
"The metric units system (e.g. Celsius, kilometers, etc)."
]
}
},
"type": "object"
}
},
"description": "Request for the LookupWeather method - represents the weather conditions at the requested location."
}