- name
- google-maps
- description
- >
- version
- 3.2.0
- author
- Leo 🦁
- tags
- [maps, places, location, navigation, google, traffic, directions, geocoding, routes-api]
- metadata
- {"clawdbot":{"emoji":"🗺️","requires":{"env":["GOOGLE_API_KEY"],"python":["requests"]},"primaryEnv":"GOOGLE_API_KEY","secondaryEnv":["GOOGLE_MAPS_API_KEY"],"optionalEnv":["GOOGLE_MAPS_LANG"],"notes":"Requires the 'requests' Python package (pip install requests). No other external dependencies."}}
- allowed-tools
- [exec]
Google Maps 🗺️
Google Maps integration powered by the Routes API.
Requirements
GOOGLE_API_KEYenvironment variable- Enable in Google Cloud Console: Routes API, Places API, Geocoding API
- Python package:
requests(pip install requests)
Configuration
| Env Variable | Default | Description |
|---|---|---|
GOOGLE_API_KEY | - | Required. Your Google Maps API key |
GOOGLE_MAPS_API_KEY | - | Alternative to GOOGLE_API_KEY (fallback) |
GOOGLE_MAPS_LANG | en | Response language (en, he, ja, etc.) |
Set in OpenClaw config:
{
"env": {
"GOOGLE_API_KEY": "AIza...",
"GOOGLE_MAPS_LANG": "en"
}
}Script Location
python3 skills/google-maps/lib/map_helper.py <action> [options]Actions
distance - Calculate travel time
python3 skills/google-maps/lib/map_helper.py distance "origin" "destination" [options]Options:
| Option | Values | Description |
|---|---|---|
--mode | driving, walking, bicycling, transit | Travel mode (default: driving) |
--depart | now, +30m, +1h, 14:00, 2026-02-07 08:00 | Departure time |
--arrive | 14:00 | Arrival time (transit only) |
--traffic | best_guess, pessimistic, optimistic | Traffic model |
--avoid | tolls, highways, ferries | Comma-separated |
Examples:
python3 skills/google-maps/lib/map_helper.py distance "New York" "Boston"
python3 skills/google-maps/lib/map_helper.py distance "Los Angeles" "San Francisco" --depart="+1h"
python3 skills/google-maps/lib/map_helper.py distance "Chicago" "Detroit" --depart="08:00" --traffic=pessimistic
python3 skills/google-maps/lib/map_helper.py distance "London" "Manchester" --mode=transit --arrive="09:00"
python3 skills/google-maps/lib/map_helper.py distance "Paris" "Lyon" --avoid=tolls,highwaysResponse:
{
"distance": "215.2 mi",
"distance_meters": 346300,
"duration": "3 hrs 45 mins",
"duration_seconds": 13500,
"static_duration": "3 hrs 30 mins",
"duration_in_traffic": "3 hrs 45 mins"
}directions - Turn-by-turn route
python3 skills/google-maps/lib/map_helper.py directions "origin" "destination" [options]Additional options (beyond distance):
| Option | Description |
|---|---|
--alternatives | Return multiple routes |
--waypoints | Intermediate stops (pipe-separated) |
--optimize | Optimize waypoint order (TSP) |
Examples:
python3 skills/google-maps/lib/map_helper.py directions "New York" "Washington DC"
python3 skills/google-maps/lib/map_helper.py directions "San Francisco" "Los Angeles" --alternatives
python3 skills/google-maps/lib/map_helper.py directions "Miami" "Orlando" --waypoints="Fort Lauderdale|West Palm Beach" --optimizeResponse includes: summary, labels, duration, static_duration, warnings, steps[], optimized_waypoint_order
matrix - Distance matrix
Calculate distances between multiple origins and destinations:
python3 skills/google-maps/lib/map_helper.py matrix "orig1|orig2" "dest1|dest2"Example:
python3 skills/google-maps/lib/map_helper.py matrix "New York|Boston" "Philadelphia|Washington DC"Response:
{
"origins": ["New York", "Boston"],
"destinations": ["Philadelphia", "Washington DC"],
"results": [
{"origin_index": 0, "destination_index": 0, "distance": "97 mi", "duration": "1 hr 45 mins"},
{"origin_index": 0, "destination_index": 1, "distance": "225 mi", "duration": "4 hrs 10 mins"}
]
}geocode - Address to coordinates
python3 skills/google-maps/lib/map_helper.py geocode "1600 Amphitheatre Parkway, Mountain View, CA"
python3 skills/google-maps/lib/map_helper.py geocode "10 Downing Street, London"reverse - Coordinates to address
python3 skills/google-maps/lib/map_helper.py reverse 40.7128 -74.0060 # New York City
python3 skills/google-maps/lib/map_helper.py reverse 51.5074 -0.1278 # Londonsearch - Find places
python3 skills/google-maps/lib/map_helper.py search "coffee near Times Square"
python3 skills/google-maps/lib/map_helper.py search "pharmacy in San Francisco" --opendetails - Place information
python3 skills/google-maps/lib/map_helper.py details "<place_id>"Traffic Models
| Model | Use Case |
|---|---|
best_guess | Default balanced estimate |
pessimistic | Important meetings (worst-case) |
optimistic | Best-case scenario |
Regional Notes
Some features may not be available in all countries:
| Feature | Availability |
|---|---|
--fuel-efficient | US, EU, select countries |
--shorter | Limited availability |
--mode=two_wheeler | Asia, select countries |
Check Google Maps coverage for details.
Multilingual Support
Works with addresses in any language:
# Hebrew
python3 skills/google-maps/lib/map_helper.py distance "תל אביב" "ירושלים"
python3 skills/google-maps/lib/map_helper.py geocode "דיזנגוף 50, תל אביב"
# Japanese
python3 skills/google-maps/lib/map_helper.py distance "東京" "大阪"
# Arabic
python3 skills/google-maps/lib/map_helper.py distance "دبي" "أبو ظبي"Language configuration:
- Set default via env:
GOOGLE_MAPS_LANG=he(persists) - Override per-request:
--lang=ja
# Set Hebrew as default in OpenClaw config
GOOGLE_MAPS_LANG=he
# Override for specific request
python3 skills/google-maps/lib/map_helper.py distance "Tokyo" "Osaka" --lang=jaHelp
python3 skills/google-maps/lib/map_helper.py help