# Apify Google Maps Directions API

> Get Google Maps directions as structured JSON with the Apify Google Maps Directions API Actor (johnvc/google-maps-directions-api). Give a start and end point as an address, GPS coordinates, or a Google Maps place ID, pick a travel mode (best, driving, cycling, walking, transit, flight, two-wheeler), and get route options back with formatted_distance, formatted_duration, a via summary, turn-by-turn steps, a per-mode durations summary, resolved place coordinates, and a google_maps_directions_url. Use when the user wants a google maps directions api, route data as JSON, distance and ETA between two addresses, turn-by-turn directions inside a script or agent, or directions without a Google Cloud API key. Pay-per-route billing, MCP-ready for Claude and other AI agents.

- Skill: `johnisanerd/apify-google-maps-directions-api` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add johnisanerd/apify-google-maps-directions-api`
- Raw SKILL.md: https://api.skillmd.com/api/skills/johnisanerd/apify-google-maps-directions-api/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- License: MIT
- Author: johnisanerd (https://skillmd.com/u/johnisanerd)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/johnisanerd/apify-google-maps-directions-api

---


# Google Maps Directions API: Routes and ETAs as JSON

One call takes an origin and a destination and returns every route option Google offers, with distance, travel time, the roads or lines used, and turn-by-turn steps. No Google Cloud project and no API key of your own.

## When to use this skill

- The user wants a Google Maps directions API they can call from code or an agent.
- They want distance, ETA, or travel time between two addresses as JSON.
- They want turn-by-turn steps, a transit itinerary, or a shareable Google Maps link.
- They ask how to get directions data without setting up Google Cloud billing.

Not for: finding or geocoding the places themselves (use the Google Maps Places API Actor), local business search (use the Google Local API Actor), or multi-stop optimization, which this Actor does not do.

## What you get (one row per route lookup)

Top level: `result_type`, `start`, `end`, `travel_mode`, `directions_found`, `directions_count`, `best_duration` ("8 min"), `best_distance` ("1.1 miles"), `google_maps_directions_url`, `gl`, `hl`, `fetched_at`.

`places_info`: the resolved origin and destination, each with `address`, `data_id` (place ID), and `gps_coordinates` (`latitude`, `longitude`).

`durations`: a compact per-mode summary of the same trip, one entry per mode with `travel_mode`, `duration` (seconds), and `formatted_duration`. A Manhattan test route returned Driving, Transit, Walking, and Cycling in a single lookup.

`directions`: one entry per route option, each with `travel_mode`, `distance` and `duration` (meters and seconds), `formatted_distance`, `formatted_duration`, `via` (route summary such as "Broadway" or "every 7 min"), and `trips`. Transit options also carry `cost` and `currency` (the fare), `start_time`, and `end_time` when present. Some options carry an `elevation_profile` with ascent, descent, and min/max altitude when present.

`trips`: legs of a route option, each with `travel_mode`, `title`, `distance`, `duration`, `formatted_distance`, `formatted_duration`, and `icon`. Transit legs add `start_stop`, `end_stop`, and `stops` (each with `name`, `data_id`, `time`) plus `service_run_by` (`name`, `link`, `route_information`) when present.

`trips[].details`: the turn-by-turn steps, each with `title` ("Head toward 6th Ave"), `action` when present, `distance`, `duration`, formatted variants, `extensions` (notes such as "Destination will be on the left"), `gps_coordinates` when present, `icon`, and sometimes a `geo_photo` street view thumbnail.

Error rows come back with `result_type` of `error`, plus `error_message` and `error_type`. A route that resolved but found nothing comes back with `directions_found` false and a short `note`.

## Prerequisites

- Apify account (sign up at https://apify.com?fpr=9n7kx3&fp_sid=skillrepo).
- Authentication via `apify login`, or an `APIFY_TOKEN` environment variable (Apify Console, Settings, Integrations).

## The Actor

- Store page: https://apify.com/johnvc/google-maps-directions-api?fpr=9n7kx3&fp_sid=skillrepo
- Actor ID: `johnvc/google-maps-directions-api`
- Pricing: pay per event, dominated by a per-route lookup fee plus a per-run setup fee (see `references/gotchas.md`).

## Run it with the Apify CLI

A basic route, best options across all modes:

```bash
apify actors call "johnvc/google-maps-directions-api" -i '{"start_addr":"Empire State Building, New York, NY","end_addr":"Times Square, New York, NY","travel_mode":"best","distance_unit":"miles"}' \
  --json \
  --user-agent apify-awesome-skills/apify-google-maps-directions-api \
  2>/dev/null
```

Driving only, avoiding tolls, arriving by a set time:

```bash
apify actors call "johnvc/google-maps-directions-api" -i '{"start_addr":"Denver, CO","end_addr":"Boulder, CO","travel_mode":"driving","avoid_tolls":true,"time_type":"arrive_by","time_value":"2026-08-03T09:00:00","distance_unit":"miles"}' \
  --json \
  --user-agent apify-awesome-skills/apify-google-maps-directions-api \
  2>/dev/null
```

Exact points by coordinates, transit with fewer transfers:

```bash
apify actors call "johnvc/google-maps-directions-api" -i '{"start_coords":"51.5007,-0.1246","end_coords":"51.5194,-0.1270","travel_mode":"transit","transit_routing":"fewer_transfers","gl":"gb","hl":"en"}' \
  --json \
  --user-agent apify-awesome-skills/apify-google-maps-directions-api \
  2>/dev/null
```

Read the rows from a finished run:

```bash
apify datasets get-items DATASET_ID --format json --user-agent apify-awesome-skills/apify-google-maps-directions-api 2>/dev/null
```

Every call carries the three flags this repo expects: `--json` (or `--format json`), `--user-agent apify-awesome-skills/apify-google-maps-directions-api`, and `2>/dev/null`.

## Run it from Claude or another AI agent (MCP)

The Actor is MCP-ready. Add the hosted server URL:

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

Then ask, for example: "How long does it take to drive from Austin to San Antonio, and what are the turn-by-turn steps?" MCP setup docs: https://docs.apify.com/platform/integrations/mcp

## Workflow

1. Pick how you name the two points. Address strings are the simplest. Use `start_coords` and `end_coords` for exact GPS points, or `start_data_id` and `end_data_id` for a specific Google Maps place. Coordinates win over place ID, and place ID wins over address.
2. Choose a travel mode. Leave `travel_mode` at `best` to see every option in one lookup, which is usually the cheapest way to answer a comparison question. Restrict it only when the user cares about a single mode.
3. Add the constraints that matter. Toll, highway, and ferry avoidance are preferences, not guarantees. Transit preferences apply only in transit mode. Set `time_type` to `depart_at` or `arrive_by` with an ISO 8601 `time_value` for a scheduled trip.
4. Set `distance_unit` and localization (`gl`, `hl`) so the strings come back in the units and language the user expects.
5. Run it, then read the row. For a quick answer use `best_duration`, `best_distance`, and `durations`. For a full itinerary walk `directions[].trips[].details`.
6. Repeat per route. One run covers one origin and destination pair, so a batch of lanes is a loop of runs. Budget accordingly, see `references/gotchas.md`.

## Inputs

- `start_addr`, `end_addr` (string): origin and destination as an address or place name
- `start_coords`, `end_coords` (string): "latitude,longitude", overrides the address
- `start_data_id`, `end_data_id` (string): Google Maps place data ID, overrides the address
- `travel_mode` (enum, default `best`): `best`, `driving`, `cycling`, `walking`, `transit`, `flight`, `two-wheeler`
- `distance_unit` (enum, default `auto`): `auto`, `km`, `miles`
- `avoid_tolls`, `avoid_highways`, `avoid_ferries` (boolean, default false)
- `transit_prefer` (enum, default `none`): `none`, `bus`, `subway`, `train`, `tram`, `light_rail`
- `transit_routing` (enum, default `none`): `none`, `fewer_transfers`, `less_walking`, `wheelchair`
- `time_type` (enum, default `leave_now`): `leave_now`, `depart_at`, `arrive_by`
- `time_value` (string): ISO 8601 datetime or Unix timestamp, used with `depart_at` or `arrive_by`
- `hl` (string, default `en`) and `gl` (string, default `us`): language and country codes

## Cost

Billing is per event. Each run pays a setup fee plus one route lookup fee, so cost scales with the number of origin and destination pairs you ask about, not with how many route options come back. A single lookup lands around two and a half cents. Live per-event prices and batch math are in `references/gotchas.md`.

## Honest limits

- One origin and destination pair per run. There is no waypoint or multi-stop input, and no built-in route optimization.
- Flight and two-wheeler modes only resolve for some regions and routes.
- Avoidance flags are preferences. Google can still return a toll or highway route when no alternative exists.
- Durations are strings plus seconds for the requested time context. There is no separate historical or predicted traffic series.
- Transit fares (`cost`, `currency`) and elevation data appear only for the options that have them.

## Troubleshooting

- `directions_found` false with a `note`: the points resolved but that mode has no route. Switch to `best`, or widen the mode.
- `result_type` of `error` with `MissingRequiredParameter`: give at least one origin field and one destination field.
- Wrong city matched: the address was ambiguous. Add state or country, or switch to `start_coords` and `end_coords`.
- Transit preferences ignored: they only apply when `travel_mode` is `transit`.
- Times look shifted: `time_value` is interpreted against the route's region, so double check `gl` for non-US routes.

See `references/gotchas.md` for cost guardrails and error recovery, and `references/actor-index.md` for the Actor routing table.

## Related mapping Actors

- Google Maps Places API: https://apify.com/johnvc/google-maps-places-api?fpr=9n7kx3&fp_sid=skillrepo
- Google Local API: https://apify.com/johnvc/google-local-api?fpr=9n7kx3&fp_sid=skillrepo
- Google Maps Contributor Reviews API: https://apify.com/johnvc/google-maps-contributor-reviews-api?fpr=9n7kx3&fp_sid=skillrepo