Google Maps Routing Skill

June 6, 2026 ยท View on GitHub

AI-first Google Maps Routes API and Geocoding API toolkit for address lookup, traffic-aware driving time, and leave-by planning.

This repository is designed to be publishable with only fake examples. It does not contain API keys, private addresses, private 1Password references, or workspace-local paths.

What This Skill Provides

  • doctor verifies credential loading and endpoint configuration.
  • geocode resolves a natural-language address through Google Geocoding API.
  • route computes a driving route through Google Routes API with traffic-aware duration.
  • The Python package exposes reusable clients for agents that need a library contract instead of a CLI.

Install

uv venv
source .venv/bin/activate
uv pip install -e '.[dev]'

Copy .env.example to .env and provide exactly one credential source:

cp .env.example .env

This skill explicitly supports two .env credential backends:

# Raw API key backend
GOOGLE_MAPS_API_KEY=replace-with-your-real-google-maps-api-key

# 1Password backend
GOOGLE_MAPS_API_KEY_OP_REFERENCE=op://your-vault/your-item/your-field

Use one backend at a time. If both are set, GOOGLE_MAPS_API_KEY wins. The 1Password reference is resolved by running op read "$GOOGLE_MAPS_API_KEY_OP_REFERENCE". Real keys and real 1Password references belong only in gitignored .env files or private workspace overlays.

Google Maps API Setup

This repo uses a bring-your-own API key model. Each user or workspace creates its own Google Cloud project and API key. No shared key is distributed.

Step 1: Create Or Select A Google Cloud Project

  1. Open Google Cloud Console.
  2. Create a project for this skill, for example google-maps-routing-skill, or select an existing project.
  3. Confirm the project selector shows the intended project before enabling APIs or creating keys.

Step 2: Enable Billing

Google Maps Platform APIs require billing on the project, even when usage stays within free monthly credits.

  1. Open Billing.
  2. Link a billing account to the project.
  3. Return to the project API dashboard after billing is attached.

Step 3: Enable APIs

Enable these APIs in the selected project:

  1. Routes API
  2. Geocoding API

Verify both appear in Enabled APIs & services. route depends on Routes API. geocode depends on Geocoding API. Routes API can accept address strings directly, so routing may work even when Geocoding API still returns REQUEST_DENIED.

Step 4: Create An API Key

  1. Open Credentials.
  2. Click CREATE CREDENTIALS and choose API key.
  3. Copy the key into your private environment, not into tracked files.

For raw API key .env usage:

GOOGLE_MAPS_API_KEY=replace-with-your-real-google-maps-api-key

For 1Password-backed .env usage:

GOOGLE_MAPS_API_KEY_OP_REFERENCE=op://your-vault/your-item/your-field

Step 5: Restrict The API Key

Do not leave the key unrestricted, regardless of whether .env stores the raw key or a 1Password reference.

  1. On the API key details page, set API restrictions to Restrict key.
  2. Allow only Routes API and Geocoding API.
  3. For local CLI usage, application restrictions are often left as None because the key is used from a developer machine. If the key is deployed to a server, use an IP or workload-specific restriction that matches that runtime.
  4. Save and wait a few minutes for restrictions to propagate.

Step 6: Verify With The CLI

From the repo root:

scripts/google_maps_routing doctor --format json
scripts/google_maps_routing geocode "1600 Amphitheatre Parkway, Mountain View, CA" --format json
scripts/google_maps_routing route --origin "San Francisco International Airport" --destination "1600 Amphitheatre Parkway, Mountain View, CA" --departure-time now --format json

Expected signals:

  • doctor exits 0 and shows a masked key.
  • geocode returns a formatted address and coordinates.
  • route returns duration_seconds, distance_meters, departure time, and arrival time.

Agent Installation Pattern

This is a loose Markdown-based skill, not a vendor-specific package. To install it into an AI workspace, an agent should:

  1. Clone or vendor this repository into a stable project directory.
  2. Read the target workspace's AGENTS.md, CLAUDE.md, or routing file such as WORKSPACE.md.
  3. Add one global pointer to skills/skill_google_maps_routing.md from the workspace skill index.
  4. Put real credentials in the target workspace's gitignored .env, using either GOOGLE_MAPS_API_KEY or GOOGLE_MAPS_API_KEY_OP_REFERENCE.
  5. Keep private aliases, local paths, and real secret references in the target workspace overlay, not in this public repository.

CLI Reference

scripts/google_maps_routing doctor [--format text|json]
scripts/google_maps_routing geocode "<address>" [--format text|json]
scripts/google_maps_routing route --origin "<address>" --destination "<address>" --departure-time now [--format text|json]
scripts/google_maps_routing route --origin "<address>" --destination "<address>" --arrival-time 2026-04-05T13:00:00-07:00 [--format text|json]

The equivalent Python module entry point is:

.venv/bin/python -m google_maps_routing.cli doctor --format json

Testing

Default tests do not call Google APIs:

.venv/bin/python -m pytest -v

Live tests require explicit opt-in and a configured credential:

RUN_LIVE_E2E=1 .venv/bin/python -m pytest -v -m live_integration

Troubleshooting

REQUEST_DENIED usually means the API is disabled, billing is missing, the key is restricted to the wrong APIs, or the key restriction has not propagated yet.

Timestamp must be set to a future time means the request sent a near-current or past departureTime. The CLI treats --departure-time now specially and avoids sending a fragile explicit timestamp.

If doctor fails with a missing key error, set either GOOGLE_MAPS_API_KEY or GOOGLE_MAPS_API_KEY_OP_REFERENCE in a gitignored .env file.