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:

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:

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:

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:

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