feat: Add Isochrones, Routes v2, Places v1, Solar, Air Quality, and Pollen APIs with CUJ samples, integration tests, and GitHub Actions CI secret support

- Added Isochrones API (generate_isochrones) for computing reachability polygons.
- Added Routes API (v2) (compute_routes, compute_route_matrix) for modern directions and travel matrices.
- Added Places API (New / v1) (places_search_text, places_search_nearby, place_v1, places_autocomplete_v1, place_photo_v1).
- Added Solar API (find_closest_building_insights, get_solar_data_layers).
- Added Air Quality API (air_quality_current_conditions).
- Added Pollen API (pollen_forecast).
- Updated Client request handling in googlemaps/client.py to merge custom HTTP headers (such as X-Goog-FieldMask).
- Added executable CUJ sample scripts suite in samples/ (real estate, logistics, travel discovery, pandas pipeline, fleet solver matrix, telemetry snapping, 15-minute city isochrones).
- Added live API integration test suite in tests/test_integration.py (verifying Devils Tower places search, Googleplex geocoding, Routes v2, Mount Everest elevation, and Address Validation).
- Configured GitHub Actions workflow (.github/workflows/test.yml) to ingest secrets.GOOGLE_MAPS_API_KEY for automated live integration runs across Python 3.9 - 3.13.
- Updated README.md with comprehensive modern API Key setup, security restrictions, local execution, and GitHub Actions secret configuration.
- Achieved 90% statement coverage across python library code (138 passing unit tests).

Author: dkhawk

googlemaps/airquality.py

@@ -0,0 +1,66 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Performs requests to the Google Maps Air Quality API."""
+
+from googlemaps import convert
+from googlemaps import exceptions
+
+_AIRQUALITY_BASE_URL = "https://airquality.googleapis.com"
+
+
+def _airquality_extract(response):
+    if response.status_code != 200:
+        try:
+            body = response.json()
+            if "error" in body:
+                raise exceptions.ApiError(
+                    body["error"].get("status", response.status_code),
+                    body["error"].get("message"),
+                )
+        except ValueError:
+            pass
+        raise exceptions.HTTPError(response.status_code)
+    return response.json()
+
+
+def air_quality_current_conditions(
+    client,
+    location,
+    extra_computations=None,
+    language_code=None,
+    uaqi_color_palette=None,
+):
+    lat, lng = convert.normalize_lat_lng(location)
+    params = {
+        "location": {
+            "latitude": lat,
+            "longitude": lng,
+        }
+    }
+
+    if extra_computations:
+        params["extraComputations"] = convert.as_list(extra_computations)
+    if language_code:
+        params["languageCode"] = language_code
+    if uaqi_color_palette:
+        params["uaqiColorPalette"] = uaqi_color_palette
+
+    return client._request(
+        "/v1/currentConditions:lookup",
+        {},
+        base_url=_AIRQUALITY_BASE_URL,
+        extract_body=_airquality_extract,
+        post_json=params,
+    )

googlemaps/client.py

@@ -303,7 +303,15 @@ def _request(self, url, params, first_request_time=None, retry_counter=0,
         # Default to the client-level self.requests_kwargs, with method-level
         # requests_kwargs arg overriding.
         requests_kwargs = requests_kwargs or {}
+
+        # Safely merge headers to preserve default headers (e.g. User-Agent)
+        client_headers = self.requests_kwargs.get("headers", {})
+        request_headers = requests_kwargs.get("headers", {})
+        merged_headers = dict(client_headers, **request_headers)
+
         final_requests_kwargs = dict(self.requests_kwargs, **requests_kwargs)
+        if merged_headers:
+            final_requests_kwargs["headers"] = merged_headers
 
         # Determine GET/POST.
         requests_method = self.session.get
@@ -428,6 +436,18 @@ def _generate_auth_url(self, path, params, accepts_clientid):
 from googlemaps.places import places_autocomplete_query
 from googlemaps.maps import static_map
 from googlemaps.addressvalidation import addressvalidation
+from googlemaps.routes import compute_routes, compute_route_matrix
+from googlemaps.solar import find_closest_building_insights, get_solar_data_layers
+from googlemaps.airquality import air_quality_current_conditions
+from googlemaps.pollen import pollen_forecast
+from googlemaps.places_v1 import (
+    places_search_text,
+    places_search_nearby,
+    place_v1,
+    places_autocomplete_v1,
+    place_photo_v1,
+)
+from googlemaps.isochrones import generate_isochrones
 
 def make_api_method(func):
     """
@@ -472,6 +492,18 @@ def wrapper(*args, **kwargs):
 Client.places_autocomplete_query = make_api_method(places_autocomplete_query)
 Client.static_map = make_api_method(static_map)
 Client.addressvalidation = make_api_method(addressvalidation)
+Client.compute_routes = make_api_method(compute_routes)
+Client.compute_route_matrix = make_api_method(compute_route_matrix)
+Client.find_closest_building_insights = make_api_method(find_closest_building_insights)
+Client.get_solar_data_layers = make_api_method(get_solar_data_layers)
+Client.air_quality_current_conditions = make_api_method(air_quality_current_conditions)
+Client.pollen_forecast = make_api_method(pollen_forecast)
+Client.places_search_text = make_api_method(places_search_text)
+Client.places_search_nearby = make_api_method(places_search_nearby)
+Client.place_v1 = make_api_method(place_v1)
+Client.places_autocomplete_v1 = make_api_method(places_autocomplete_v1)
+Client.place_photo_v1 = make_api_method(place_photo_v1)
+Client.generate_isochrones = make_api_method(generate_isochrones)
 
 
 def sign_hmac(secret, payload):

googlemaps/isochrones.py

@@ -0,0 +1,66 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Performs requests to the Google Maps Isochrones API."""
+
+from googlemaps import convert
+from googlemaps import exceptions
+from googlemaps.routes import route_waypoint
+
+_ISOCHRONES_BASE_URL = "https://isochrones.googleapis.com"
+
+
+def _isochrones_extract(response):
+    if response.status_code != 200:
+        try:
+            body = response.json()
+            if "error" in body:
+                raise exceptions.ApiError(
+                    body["error"].get("status", response.status_code),
+                    body["error"].get("message"),
+                )
+        except ValueError:
+            pass
+        raise exceptions.HTTPError(response.status_code)
+    return response.json()
+
+
+def generate_isochrones(
+    client,
+    location,
+    travel_mode="DRIVE",
+    duration_seconds=None,
+    distance_meters=None,
+    routing_preference=None,
+):
+    params = {
+        "origin": route_waypoint(location),
+        "travelMode": travel_mode,
+    }
+
+    if duration_seconds is not None:
+        params["range"] = {"duration": "%ds" % duration_seconds}
+    elif distance_meters is not None:
+        params["range"] = {"distanceMeters": distance_meters}
+
+    if routing_preference:
+        params["routingPreference"] = routing_preference
+
+    return client._request(
+        "/v1/isochrones:generate",
+        {},
+        base_url=_ISOCHRONES_BASE_URL,
+        extract_body=_isochrones_extract,
+        post_json=params,
+    )