How to connect Google Maps MCP with Codex

Call this tool when the user's request is to find places, businesses, addresses, locations, points of interest, or any other Google Maps related search. **Input Requirements (CRITICAL):** 1. **`text_query` (string - MANDATORY):** The primary search query. This must clearly define what the user is looking for. * **Examples:** `'restaurants in New York'`, `'coffee shops near Golden Gate Park'`, `'SF MoMA'`, `'1600 Amphitheatre Pkwy, Mountain View, CA, USA'`, `'pets friendly parks in Manhattan, New York'`, `'date night restaurants in Chicago'`, `'accessible public libraries in Los Angeles'`. * **For specific place details:** Include the requested attribute (e.g., `'Google Store Mountain View opening hours'`, `'SF MoMa phone number'`, `'Shoreline Park Mountain View address'`). 2. **`location_bias` (object - OPTIONAL):** Use this to prioritize results near a specific geographic area. * **Format:** `{"location_bias": {"circle": {"center": {"latitude": [value], "longitude": [value]}, "radius_meters": [value (optional)]}}}` * **Usage:** * **To bias to a 5km radius:** `{"location_bias": {"circle": {"center": {"latitude": 34.052235, "longitude": -118.243683}, "radius_meters": 5000}}}` * **To bias strongly to the center point:** `{"location_bias": {"circle": {"center": {"latitude": 34.052235, "longitude": -118.243683}}}}` (omitting `radius_meters`). 3. **`language_code` (string - OPTIONAL):** The language to show the search results summary in. * **Format:** A two-letter language code (ISO 639-1), optionally followed by an underscore and a two-letter country code (ISO 3166-1 alpha-2), e.g., `en`, `ja`, `en_US`, `zh_CN`, `es_MX`. If the language code is not provided, the results will be in English. 4. **`region_code` (string - OPTIONAL):** The Unicode CLDR region code of the user. This parameter is used to display the place details, like region-specific place name, if available. The parameter canaffect results based on applicable law. * **Format:** A two-letter country code (ISO 3166-1 alpha-2), e.g., `US`, `CA`. **Instructions for Tool Call:** * Location Information (CRITICAL): The search must contain sufficient location information. If the location is ambiguous (e.g., just "pizza places"), *you must* specify it in the `text_query` (e.g., "pizza places in New York") or use the `location_bias` parameter. Include city, state/province, and region/country name if needed for disambiguation. * Always provide the most specific and contextually rich `text_query` possible. * Only use `location_bias` if coordinates are explicitly provided or if inferring a location from a user's known context is appropriate *and* necessary for better results. * The grounded output must be attributed to the source using the information from the `attribution` field when available.

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 states the supported range. Do **not** call a different date, hour, or domain as a substitute. **Domain Options & Attribution:** * **Language (`language_code`):** Optional BCP-47 language code (e.g., `"fr"`). Defaults to `"en"`. * **Weather Units (`weather_options.units_system` or `units_system`):** Defaults to `METRIC`. Set to `IMPERIAL` (Fahrenheit/mph) if the user implies US standards or explicitly requests Imperial units. Supported in both `weather_options.units_system` (preferred) and top-level `units_system`; if both are specified, they must not conflict. * **Air Quality Options (`air_quality_options`):** Set `include_pollutant_concentration: true` when specific pollutant concentrations (PM2.5, PM10, O3, NO2, SO2, CO) are needed; optionally set `index_region_code` (2-letter ISO country code, e.g., `"US"`) to request a specific regional AQI scale. By default, the response includes the Universal AQI and the location's regional AQI. * **Attribution:** Grounded output MUST be attributed to the source using the `attribution` field inside each returned domain container (`weather.attribution`, `air_quality.attribution`, `pollen.attribution`). * **Returned Times:** Air Quality `date_time` values are already in the location's local time (`utc_offset` included); present them as-is. Weather `date_time` (current and hourly) and sunrise/sunset times are UTC; convert them to the location's local time using `time_zone`. Label all times as local.

Computes travel routes between an origin and a destination, optionally through intermediate stops. Returns the distance and duration for each route. **Input Requirements (CRITICAL):** 1. **`origin` and `destination` (objects - MANDATORY):** Each must be provided using exactly one of: * **`address`** (string, e.g., `'Eiffel Tower, Paris'`). Named places, landmarks, and businesses are resolved directly, so do NOT call `search_places` first just to geocode a waypoint. Include any city, region, or country the user mentioned. * **`lat_lng`** (object, `{"latitude": number, "longitude": number}`). * **`place_id`** (string, e.g., `'ChIJOwE_Id1w5EAR4Q27FkL6T_0'`), for example from `search_places`. 2. **`intermediate_waypoints` (array of objects - OPTIONAL):** Up to 10 stops to pass through, in order, between the origin and destination. Same format as `origin`. Not supported with `TRANSIT`. Only include stops the user asked for. 3. **`travel_mode` (enum - OPTIONAL):** `DRIVE` (default), `WALK`, `BICYCLE`, or `TRANSIT`. 4. **Timing (OPTIONAL - set at most ONE):** RFC 3339 timestamps with a UTC offset, e.g., `'2026-09-19T08:00:00-07:00'`. Defaults to departing now. For `TRANSIT`, the time can be up to 7 days in the past or up to 100 days in the future. For other modes, the time can be up to 365 days in the future and must not be in the past. * **`departure_time`:** Use when the user says when they will leave (e.g., "tomorrow at 8am"). * **`arrival_time`:** Use when the user says when they must arrive (e.g., "be there by 9am"). 5. **`routing_preference` (enum - OPTIONAL):** * `ROUTING_PREFERENCE_TRAFFIC_UNAWARE` (default): ignores live traffic, incidents, and closures. Lowest latency. * `ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL`: uses live traffic conditions when available. Not supported for `WALK` or `BICYCLE`. Set this ONLY when the user asks about traffic, congestion, or a traffic-adjusted ETA. It incurs higher cost and latency. 6. **`location_bias` (object - OPTIONAL):** `{"latitude": number, "longitude": number}` used to disambiguate place names in waypoint addresses. If a name is ambiguous (e.g., "Springfield") and the user gave no region, keep the name as given in `address` and set `location_bias` toward the intended area instead of guessing a region. 7. **`compute_alternative_routes` (boolean - OPTIONAL):** Set to `true` only when the user asks for route options or alternatives. Defaults to `false`, which returns only the recommended route. 8. **`include_polyline` (boolean - OPTIONAL):** Set to `true` only when the route geometry (`encoded_polyline`) is needed. Defaults to `false`. **Instructions for Tool Call:** * If the origin or the destination is missing, **you MUST ask the user for clarification** before calling the tool. * For "How far is A from B?" questions, use B as the `origin` and A as the `destination`. **Example Tool Call:** {"origin":{"address":"Eiffel Tower"},"destination":{"place_id":"ChIJt_5xIthw5EARoJ71mGq7t74"},"intermediate_waypoints":[{"address":"Louvre Museum"}],"travel_mode":"DRIVE","departure_time":"2026-09-19T08:00:00+02:00"} **Instructions for Response:** * When alternative routes are requested, routes are ordered from most to least recommended. * If `routes` is empty, tell the user no route was found. Do not guess a route. * To find places along a `DRIVE` route, pass the route's `retrieval_token` to `search_along_route`. The token is valid for 10 minutes. * Only state facts returned by the tool. Do NOT invent turn-by-turn directions, transit lines, stations, platforms, or transfers. * The grounded output must be attributed to the source using each route's `attribution` field when available.

Call this tool when the user wants to find places, businesses, or points of interest along a travel route (e.g., "gas stations on my way to Tahoe", "coffee shops between SF and San Jose"). Calling this tool incurs higher cost than `search_places`, so use `search_places` instead when searching near a single location rather than along a route. **Input Requirements (CRITICAL):** 1. **`text_query` (string - MANDATORY):** A natural language description of what to search for along the route. * **Examples:** `'ev chargers'`, `'coffee'`, `'vegetarian restaurants'`, `'rest stops'`. 2. **Route specification (MANDATORY - provide exactly ONE of the following):** * **`retrieval_token` (string):** The `retrieval_token` returned by a prior `compute_routes` call for a `DRIVE` route. Prefer this whenever the route was already computed. The token is valid for 10 minutes. * **`route_endpoints` (object):** The route's `origin` and `destination`. Each must be provided using one of `address`, `lat_lng`, or `place_id`. * **Example:** `{"route_endpoints": {"origin": {"address": "San Francisco, CA"}, "destination": {"address": "Lake Tahoe, CA"}}}` * **`encoded_polyline` (string):** An encoded polyline representing a `DRIVE` route. 3. **`travel_mode` (enum - OPTIONAL):** `DRIVE` (default), `WALK`, or `BICYCLE`. `WALK` and `BICYCLE` are only supported with `route_endpoints`. `TRANSIT` is not supported. 4. **`routing_preference` (enum - OPTIONAL):** * `ROUTING_PREFERENCE_TRAFFIC_UNAWARE` (default): computes the route and detours without live traffic. Lowest latency. * `ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL`: uses live traffic conditions when available. Not supported for `WALK` or `BICYCLE`. Set this ONLY when the user asks about traffic, congestion, or traffic-adjusted detour times. It incurs higher latency. 5. **`include_extended_details` (boolean - OPTIONAL):** Set to `true` only when the request requires qualitative review insights, specific menu items or offerings, atmosphere, visitor tips or busyness, EV charger availability, gas prices, or other rich qualitative details. Defaults to `false`. Enabling it may increase latency. 6. **`language_code` (string - OPTIONAL):** The language for the results summary and place details, e.g., `en`, `ja`, `en-US`. Defaults to `en-US`. 7. **`region_code` (string - OPTIONAL):** The Unicode CLDR region code of the user, e.g., `US`, `CA`. **Instructions for Tool Call:** * Each result includes a `detour_summary` (when available) describing the extra distance (`localized_detour_distance`) and, unless the route was given as `encoded_polyline`, the extra time (`detour_duration`) incurred by stopping at that place. Use it to compare options. * The response `summary` may contain zero-based citations (e.g., "[0]") referencing entries in `results`. * The grounded output must be attributed to the source using the `attribution` field of each `results[].place` when available.

Resolves a batch list of specific location queries (landmark names or exact addresses) into canonical Google Maps Place IDs. **Input Requirements (CRITICAL):** 1. **`queries` (array of objects - MANDATORY):** A list of location queries to resolve. You may specify up to 20 queries. * **Each query object must have:** * **`text` (string - MANDATORY):** The text query representing a specific place name or address to resolve. * **Examples:** `'Googleplex, Mountain View, CA'`, `'1600 Amphitheatre Pkwy, Mountain View, CA'`, `'Eiffel Tower, Paris'`. 2. **`location_bias` (object - OPTIONAL):** Use this to prioritize results near a specific geographic area. * **Format:** `{"viewport": {"low": {"latitude": [value], "longitude": [value]}, "high": {"latitude": [value], "longitude": [value]}}}` 3. **`region_code` (string - OPTIONAL):** The Unicode CLDR region code (two-letter country code, e.g., `US`, `CA`) of the user to bias the results. **Instructions for Tool Call:** * Specificity (CRITICAL): Queries must represent a specific place name or address. General searches like `'restaurants'` or chain names like `'Starbucks'` are not supported. * Do NOT call this tool if the downstream tools you plan to invoke already accept raw address or place name strings directly. **Save to Google Maps:** * The response includes a `save_to_maps_url` field: a single Google Maps link containing all successfully resolved places. * When the user wants to save, share, or open the resolved places as a list in Google Maps, present this link to the user. Do NOT construct this link yourself. **Error Handling (CRITICAL):** * This is a batch processing tool. A request might return "mixed results" (e.g. some queries resolve successfully while others fail). * The output list of `results` is guaranteed to map 1:1 with the input `queries` indices. A failed query will result in an empty `Result` message (no `entity` is set) at its corresponding index in the `results` list. * You **MUST** check the `failed_requests` map field in the response to identify which specific query index failed. The key of `failed_requests` represents the 0-based index of the failed query in the request. Do not assume the entire batch call failed because of a partial failure.

Resolves a list of Google Maps URLs into canonical Google Maps Place IDs. **When to call this tool (CRITICAL):** * Use this tool when the user provides one or more Google Maps sharing links or URLs (e.g. 'https://maps.app.goo.gl/...', 'https://www.google.com/maps/place/...', or 'https://maps.google.com/...') and you need to extract the underlying canonical Place IDs. * You can specify up to 20 URLs to resolve in a single batch request. **Input Requirements (CRITICAL):** * **`urls` (array of strings - MANDATORY):** The list of Google Maps URLs to resolve. Each URL must be a valid, single-place Google Maps URL. **Save to Google Maps:** * The response includes a `save_to_maps_url` field: a single Google Maps link containing all successfully resolved places. * When the user wants to save, share, or open the resolved places as a list in Google Maps (e.g. collecting places shared in a conversation), present this link to the user. Do NOT construct this link yourself. **Error Handling (CRITICAL):** * This is a batch processing tool. A request might return "mixed results" (e.g. some URLs resolve successfully while others fail). * The output list of `entities` is guaranteed to map 1:1 with the input `urls` indices. A failed URL resolution will result in an empty `Entity` message (no fields are set) at its corresponding index in the `entities` list. * You **MUST** check the `failed_requests` map field in the response to identify which specific URL index failed. The key of `failed_requests` represents the 0-based index of the failed URL in the request. Do not assume the entire batch call failed because of a partial failure.