Google Maps Directions API

Get a bounded, agent-friendly Google Maps route report between two known locations. It returns normalized dataset records with distance, duration, alternatives, route links, provider provenance, and optional turn steps for logistics planners, field-service teams, travel workflows, and AI agents. The default provider is SerpApi's Google Maps Directions engine, funded by the Actor owner, so users use owner-managed map credentials. A direct Google Routes BYOK mode remains available for Google Place IDs, up to ten ordered stops, traffic-aware routing, and encoded route polylines.

Use this Actor for route research, field-service planning, travel workflows, and AI agents that need distance, duration, alternatives, a Google Maps link, and optional turn steps. Fleet routing, navigation, toll pricing, and place discovery work well as dedicated follow-on workflow stages.

Best fit

Choose the default SERPAPI_GOOGLE_MAPS provider for a known address or coordinate pair when you want real Google Maps directions without supplying a customer key. It supports driving, walking, cycling, transit, alternatives, route preferences, localized text, and bounded turn steps.

Choose GOOGLE_ROUTES_BYOK when you own a restricted Google Maps Routes API key and need Google Place IDs, ordered intermediate stops, traffic-aware preferences, staticDurationSeconds, or an encoded polyline. The direct key is a secret input and is never written to the dataset, OUTPUT, RUN_SUMMARY, or logs.

Focused standalone workflow

This Actor works as a focused standalone workflow for one known origin-destination pair. A field-service coordinator starts with the scheduled visit address, then requests one driving route, compares its duration with the appointment window, and passes the route link plus provenance into a dispatch record.

Quick start

This default request uses the included SerpApi provider. No customer credential is required.

{
  "origin": "Times Square, New York, NY",
  "destination": "Central Park, New York, NY",
  "travelMode": "DRIVE",
  "maxRouteOptions": 1
}

For direct Google Routes features, set routeProvider to GOOGLE_ROUTES_BYOK and add a restricted Routes API key:

{
  "routeProvider": "GOOGLE_ROUTES_BYOK",
  "googleMapsApiKey": "YOUR_RESTRICTED_GOOGLE_MAPS_ROUTES_KEY",
  "origin": "placeId:ChIJmQJIxlVYwokRLgeuocVOGgQ",
  "destination": "placeId:ChIJ4zGFAZpYwokRGUGph3Mf37k",
  "intermediates": ["Grand Central Terminal, New York, NY"],
  "travelMode": "DRIVE",
  "routingPreference": "TRAFFIC_AWARE",
  "includeSteps": true
}

Input reference

Field	What it controls
routeProvider	Default SERPAPI_GOOGLE_MAPS uses owner-managed SerpApi. GOOGLE_ROUTES_BYOK makes a direct Google Routes request.
origin, destination	Required addresses or latitude,longitude pairs. placeId: values work in direct Google Routes mode.
googleMapsApiKey	Optional secret required only for direct Google Routes mode.
intermediates	Up to ten ordered stops in direct Google Routes mode.
travelMode	DRIVE, WALK, BICYCLE, or TRANSIT.
routingPreference	Google Routes driving-traffic option; keep TRAFFIC_UNAWARE for SerpApi.
computeAlternativeRoutes, maxRouteOptions	Bound the output to one through three route choices from a single provider request.
avoidTolls, avoidHighways	Route-selection preferences with provider-dependent results; toll-price estimates remain outside this contract.
languageCode, units	Two-letter instruction language and metric/imperial display preference.
includeSteps, maxStepsPerRoute	Optional bounded turn instructions, off by default for compact agent output.

Output: What you receive

One dataset row represents one route option. One completed provider request is charged once even when it returns up to three retained alternatives.

{
  "routeIndex": 0,
  "routeLabels": ["DEFAULT_ROUTE"],
  "origin": "Times Square, New York, NY",
  "destination": "Central Park, New York, NY",
  "travelMode": "DRIVE",
  "distanceMeters": 4200,
  "durationSeconds": 840,
  "staticDurationSeconds": null,
  "encodedPolyline": null,
  "googleMapsUrl": "https://www.google.com/maps/dir/...",
  "legs": [{ "legIndex": 0, "distanceMeters": 4200, "durationSeconds": 840, "steps": [] }],
  "provider": "SerpApi Google Maps Directions",
  "source": "Google Maps directions retrieved through SerpApi",
  "warnings": ["Google Maps directions were retrieved through SerpApi; encoded polyline geometry is not supplied by this provider."]
}

distanceMeters and durationSeconds are normalized numeric fields. encodedPolyline and staticDurationSeconds are populated only by the direct Google Routes BYOK provider; they are explicitly null for SerpApi records rather than guessed.

Terminal outcomes

Every run writes compact OUTPUT and detailed RUN_SUMMARY records.

Outcome	Meaning
COMPLETE	The selected provider returned route options and every retained option was persisted.
PARTIAL	At least one usable option persisted but another could not be safely written.
VALID_EMPTY	The provider accepted a valid request but returned no route option.
INVALID_INPUT	The submitted locations, provider mode, secret, or incompatible option can be corrected.
UPSTREAM_FAILED	A valid request could not be completed by its selected provider and no useful route was persisted.

Pricing and cost controls

Pay per event pricing charges $0.07 for one completed route-report provider request plus the standard $0.00005 Actor-start event and platform usage. That one event can persist one to three route records. The owner-managed SerpApi Developer plan currently costs $0.015 per successful search at its 5,000-search tier, so the $0.07 event leaves about 73% contribution margin after Apify's 20% share and the provider call, before support and operations.

Direct GOOGLE_ROUTES_BYOK requests use the same Apify event and are separately billed by Google to the caller's Cloud project. Check the live Pricing tab and your provider account before high-volume production workflows. Set maxTotalChargeUsd for Apify and a provider-side quota/budget.

Run through the Apify API

curl "https://api.apify.com/v2/acts/khadinakbar~google-maps-directions-api/runs?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "origin": "Times Square, New York, NY",
    "destination": "Central Park, New York, NY",
    "travelMode": "DRIVE",
    "maxRouteOptions": 1
  }'

Read the default dataset after processing, then inspect OUTPUT for the terminal outcome and RUN_SUMMARY for provider, counts, cost events, and safe diagnostics.

API and MCP use

Run this regular Actor through the standard Apify API or hosted Apify MCP integration, then read the default dataset for route options and OUTPUT for terminal state. For an agent workflow, ask for one bounded route, preserve provider, source, and checkedAt in downstream decisions, and inspect OUTPUT.outcome before acting on an empty dataset.

Compute a driving route from Times Square, New York to Central Park, return one route with distance and duration, include no turn steps, and preserve the provider provenance.

Best results

• Use the default SerpApi provider for addresses and coordinates without a customer credential.
• Use direct Google Routes BYOK for Place IDs, ordered stops, traffic preferences, or encoded geometry.
• Start with one route option and no steps; enable additional data only when the downstream decision needs it.
• Treat directions as planning information, not real-time navigation or a promise about current road conditions.

Builder's note

I designed the two provider contracts to be explicit. SerpApi returns Google Maps directions with owner-managed credentials and normalized route fields, while direct Google Routes preserves direct-only features. Every record identifies its actual provider and source, and explicit nulls describe fields outside the selected provider's response shape.

Responsible use

Use route data in workflows authorized by the selected provider's terms and applicable law. When using direct Google Routes, follow Google Maps Platform attribution, display, retention, and use restrictions. This Actor supports route research and planning workflows rather than real-time navigation, autonomous control, or transportation safety decisions.