Google Maps

Google Maps integration for OpenClaw with Routes API. Use for: (1) Distance/travel time calculations with traffic prediction, (2) Turn-by-turn directions, (3...

Security Scan

The skill's requirements and runtime behavior align with a Google Maps/Routes integration: it only asks for a Google Maps API key, uses Google endpoints, and instructs running a local Python helper — nothing obviously disproportionate or malicious in the provided artifacts.

Purpose & Capability

Name/description (Routes API, geocoding, places, directions, matrix) match the declared requirements: an API key (GOOGLE_API_KEY) and the 'requests' Python package. No unrelated credentials, binaries, or system paths are requested.

Instruction Scope

SKILL.md instructs the agent to run the included Python script with well-scoped actions (distance, directions, matrix, geocode, search, details). The instructions reference only the Google Maps APIs and local script execution; they do not ask the agent to read unrelated files, system secrets, or send data to non-Google endpoints in the visible content.

Install Mechanism

No install spec or third-party downloads; the only runtime dependency is 'requests' (pip). The skill is delivered as code bundled with the skill (lib/map_helper.py) and does not fetch arbitrary archives or executables from untrusted URLs.

Credentials

Only GOOGLE_API_KEY is required (with a documented fallback GOOGLE_MAPS_API_KEY and optional language env). This is appropriate for calling Google Maps/Routes/Places/Geocoding APIs and is proportionate to the stated functionality.

Persistence & Privilege

The skill does not request always: true and it runs only when invoked (user-invocable). It does not declare modifications to other skills or system-wide settings. The allowed-tool 'exec' is present to run the Python helper, which is consistent with the instructions.

Assessment

This skill appears coherent, but take these precautions before installing: (1) Use a Google API key restricted to the specific Maps APIs (Routes, Places, Geocoding) and restrict by referrer or IP to limit abuse. (2) Avoid using an unrestricted or shared API key; create a dedicated key for this skill and enable billing alerts/quotas. (3) Review the full lib/map_helper.py (the provided snippet was truncated) to confirm there are no unexpected external endpoints or secret-exfiltration code paths. (4) Ensure the environment variable GOOGLE_API_KEY is stored securely and not logged by other components; do not paste the key into public places. (5) Confirm 'requests' is installed in a controlled environment and monitor API usage after enabling the skill. If you want higher assurance, request the full source for inspection and verify there are no non-Google network calls or hard-coded endpoints before granting the key.

Google Maps integration powered by the Routes API.

Requirements

• GOOGLE_API_KEY environment 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,highways

Response:

{
  "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" --optimize

Response 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  # London

---

search - 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" --open

details - 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:

1. Set default via env: GOOGLE_MAPS_LANG=he (persists)
2. 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=ja

---

Help

python3 skills/google-maps/lib/map_helper.py help