Google Maps Directions

🗺️ Google Maps Directions API: routes, ETA, and turn-by-turn steps as JSON

The most efficient, reliable, and developer-friendly way to use the Google Maps Directions API.

Actor page: apify.com/johnvc/google-maps-directions-api Input schema: apify.com/johnvc/google-maps-directions-api/input-schema

Call the Google Maps Directions API from Python or from any MCP client and get directions between an origin and a destination as clean, structured JSON: route options for driving, transit, walking, cycling, and flight, with distance, ETA, traffic-aware duration ranges, resolved place coordinates, turn-by-turn steps, and a direct Google Maps link. Provide addresses, GPS coordinates, or place IDs.

Video Walkthrough

Quick Start

Prerequisites

• Python 3.11 or higher
• An Apify account and API key (get a free key here)

1. Clone the repository

   git clone https://github.com/johnisanerd/Apify-Google-Maps-Directions-API.git

cd Apify-Google-Maps-Directions-API

1. Install dependencies with UV

   # Install UV if you do not have it:

curl -LsSf https://astral.sh/uv/install.sh | sh

Install project dependencies:

uv sync

1. Configure your API key

   cp .env.example .env

Edit .env and add your Apify API key

Get your free API key at: https://apify.com?fpr=9n7kx3

1. Run the example

   uv run python google-maps-directions-api-example.py

Alternative: set the API key directly

export APIFY_API_TOKEN="your_api_key_here"

uv run python google-maps-directions-api-example.py

Explore every input

Once the basic run works, google-maps-directions-api-cookbook.py is a runnable catalog of every feature (all travel modes, coordinates and place-ID inputs, avoidance, units, localization, and transit time and routing). See the cookbook table under "Usage Examples" below.

Why Use This Google Maps Directions API?

Every travel mode in one call. Ask for the best options across modes, or pin a single mode: driving, transit, walking, cycling, flight, or two-wheeler. One request returns every route option Google offers for your origin and destination.

Turn-by-turn detail, structured. Each route option carries distance, duration, a traffic-aware typical duration range, a route summary, route notes (tolls, conditions), and trips broken down into individual turn-by-turn steps. Transit options include stops, lines, operators, and times.

Flexible inputs. Set your origin and destination as an address or place name, exact GPS coordinates, or a Google Maps place ID. Choose units, avoid tolls, highways, or ferries, tune transit routing, and set a departure or arrival time.

Predictable pricing. A single route lookup is one flat charge. No surprise per-step or per-byte billing.

Built for agents. The Actor is MCP-ready, so you can load it as a tool in Claude or Cursor and ask for directions in plain language (see the install sections below).

Features

Core Capabilities

• Driving, transit, walking, cycling, flight, and two-wheeler routing
• Distance, ETA, and traffic-aware duration ranges
• Turn-by-turn steps per leg, with per-step distance and duration
• Transit stops, lines, operators, and departure/arrival times
• Resolved origin/destination addresses, place IDs, and GPS coordinates
• A direct Google Maps link for each route

Data Quality

• Clean, consistent JSON with one row per lookup
• Real units, formatted and raw (meters/seconds plus human-readable strings)
• Country and language targeting for localized place names and instructions

Usage Examples

Basic Example

{

"start_addr": "New York, NY", "end_addr": "Boston, MA" }

Advanced Example

{

"start_addr": "Brooklyn, NY", "end_addr": "Times Square, New York, NY", "travel_mode": "transit", "transit_routing": "less_walking", "time_type": "arrive_by", "time_value": "2026-06-01T09:00:00", "distance_unit": "miles", "hl": "en", "gl": "us" }

Run every input from Python (cookbook)

google-maps-directions-api-cookbook.py is a runnable catalog that exercises every input the API supports, with a clean printed summary per route. Run one example by name, or all:

uv run python google-maps-directions-api-cookbook.py            # runs 'basic'

uv run python google-maps-directions-api-cookbook.py walking uv run python google-maps-directions-api-cookbook.py all # runs every example (each is billed)

Input Parameters

Provide an origin (an address, coordinates, or a place ID) and a destination.

Output Format

One row per run. Trimmed example for New York, NY to Boston, MA:

{

"result_type": "directions", "start": "New York, NY", "end": "Boston, MA", "travel_mode": "best", "directions_found": true, "directions_count": 3, "best_duration": "3 hr 38 min", "best_distance": "215 miles", "places_info": [ { "address": "New York", "data_id": "0x89c24fa5d33f083b:0xc80b8f06e177fe62", "gps_coordinates": { "latitude": 40.7127753, "longitude": -74.0059728 } }, { "address": "Boston, Massachusetts", "data_id": "0x89e3652d0d3d311b:0x787cbf240162e8a0", "gps_coordinates": { "latitude": 42.3555076, "longitude": -71.0565364 } } ], "directions": [ { "travel_mode": "Driving", "via": "CT-15 N and I-90 E", "distance": 346243, "duration": 13082, "formatted_distance": "215 miles", "formatted_duration": "3 hr 38 min", "typical_duration_range": "3 hr 21 min to 4 hr 10 min", "extensions": ["Fastest route now due to traffic conditions", "This route has tolls."], "trips": [ { "travel_mode": "Driving", "title": "Get on FDR Dr", "formatted_distance": "0.9 mi", "formatted_duration": "5 min", "details": [ { "title": "Head toward Park Row", "action": "straight", "formatted_distance": "200 ft", "formatted_duration": "21 sec" } ] } ] } ], "durations": [ { "travel_mode": "Driving", "formatted_duration": "3 hr 38 min" }, { "travel_mode": "Transit", "formatted_duration": "4 hr 25 min" }, { "travel_mode": "Flight", "formatted_duration": "1 hr 15 min" } ], "google_maps_directions_url": "https://www.google.com/maps/dir/...", "gl": "us", "hl": "en", "fetched_at": "2026-05-29T12:00:00+00:00" }

---

This Actor is MCP-server-compatible, so AI assistants can call the Google Maps Directions API as a tool through Apify's hosted MCP server.

The Actor's MCP server URL is always built with the actors and docs helper tools plus this one Actor:

https://mcp.apify.com/?tools=actors,docs,johnvc/google-maps-directions-api

The actors and docs tools let the assistant discover and read Apify docs, while preloading just this one Actor keeps the tool list small. Auth is either OAuth in the browser when offered, or your Apify API token (the same APIFY_API_TOKEN secret used by the Python example). Get a token at https://console.apify.com/settings/integrations and a free Apify account at https://apify.com?fpr=9n7kx3 .

Install in Claude Cowork Desktop

Cowork is the desktop app's automation mode. To give it the Google Maps Directions API as a tool, add the Apify MCP server as a connector.

1. Open the Claude desktop app and go to Settings → Connectors (or Settings → Developer → Edit Config to edit claude_desktop_config.json directly).

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

1. Add the Apify MCP server, preloaded with only this Actor:

{

"mcpServers": { "apify": { "command": "npx", "args": [ "-y", "mcp-remote", "https://mcp.apify.com/?tools=actors,docs,johnvc/google-maps-directions-api" ] } } }

1. Restart the app. When Cowork first calls the tool, complete the OAuth prompt in your browser, or add your Apify API token in the connector settings to skip OAuth.
2. In a Cowork chat, confirm the tool is available and ask it to run the Google Maps Directions API.

Download the desktop app and start a free trial: https://claude.ai/referral/uIlpa7nPLg More help: https://docs.apify.com/platform/integrations/claude-desktop

Install in Claude Code

Claude Code is the command-line tool. Add the Actor's MCP server with one command:

claude mcp add --transport http apify \

"https://mcp.apify.com/?tools=actors,docs,johnvc/google-maps-directions-api"

To use a token instead of browser OAuth:

claude mcp add --transport http apify \

"https://mcp.apify.com/?tools=actors,docs,johnvc/google-maps-directions-api" \ --header "Authorization: Bearer YOUR_APIFY_TOKEN"

Then verify with claude mcp list, or run /mcp inside a session. Ask Claude Code to call the Google Maps Directions API.

Try Claude Code fr