Vexaloom Labs
Actors/Google Maps Route & Distance Matrix Scraper

Google Maps Route & Distance Matrix Scraper

Get driving, walking, bicycling or transit routes between two locations - distance, duration, traffic and turn-by-turn steps - or build a travel-time matrix across many origins and destinations in one run.

Open on ApifyGitHub source

Input schema

Input fields, types, required flags, descriptions, defaults, and prefills come from the published definition. Prefill examples are distinct from defaults.

FieldTypeRequiredDescription
modestringoptionalWhat to scrape: one route (with optional waypoints), a distance matrix, or a list of Google Maps directions URLs.
stopsarrayoptionalOrdered stops for route mode: 2–10 locations. The first is the origin, the last is the destination, and everything in between becomes a waypoint.
originsarrayoptionalStarting locations for matrix mode. Each origin is paired with every destination below.
Show all input fields
FieldTypeRequiredDescription
modestringoptionalWhat to scrape: one route (with optional waypoints), a distance matrix, or a list of Google Maps directions URLs.
stopsarrayoptionalOrdered stops for route mode: 2–10 locations. The first is the origin, the last is the destination, and everything in between becomes a waypoint.
originsarrayoptionalStarting locations for matrix mode. Each origin is paired with every destination below.
destinationsarrayoptionalEnding locations for matrix mode. Each destination is paired with every origin above.
directionsUrlsarrayoptionalGoogle Maps directions links for URLs mode. Canonical /maps/dir/ links and short share links are both accepted; waypoints and travel mode are read from the link when present.
maxPairsintegeroptionalMaximum number of origin × destination pairs to request in matrix mode. Pairs beyond this cap are left out.
travelModestringoptionalHow to travel between the stops.
avoidTollsbooleanoptionalDriving only — ask Google Maps to avoid toll roads. If no toll-free route exists, Google may still return a toll route.
avoidHighwaysbooleanoptionalDriving only — ask Google Maps to avoid highways and motorways. If no practical alternative exists, Google may still return a highway route.
avoidFerriesbooleanoptionalDriving only — prefer routes without ferry crossings. If every route uses a ferry, the result is still returned and marked with avoidanceUnmet.
departureTimestringoptionalOptional ISO 8601 departure time as local time at the origin, for example 2026-06-16T10:30:00. Used for driving traffic estimates and transit schedules. A timezone offset is accepted but ignored; walking and bicycling ignore the field.
maxAlternativesintegeroptionalMaximum number of route alternatives to return per trip, including Google's recommended route. Applies to route and URLs modes. Google usually supplies up to 3 alternatives.
maxItemsintegeroptionalGlobal cap on the number of records pushed to the dataset.
includeStepsbooleanoptionalAdd turn-by-turn steps with instruction, distance, duration, maneuver, coordinates and route geometry for every returned route.
includeStreetViewbooleanoptionalAdd a Street View panorama ID and thumbnail URL to each step where Google publishes one. This also enables step details.
languagestringoptionalLanguage for instructions and other localized text.
unitsstringoptionalPreferred distance units for the formatted distance fields. Meter values stay unchanged.
requestDelayMsintegeroptionalPause between directions requests. A small delay keeps large matrix runs polite and reduces rate limiting.
proxyConfigurationobjectoptionalOptional fallback proxy. The actor first requests Google Maps directly and only retries through this proxy if the direct request is blocked.

Download the published input schema

View complete JSON
{
  "description": "Get route alternatives, multi-stop trips, turn-by-turn steps, traffic, transit detail, distance matrices and directions URLs from Google Maps.",
  "properties": {
    "avoidFerries": {
      "default": false,
      "description": "Driving only — prefer routes without ferry crossings. If every route uses a ferry, the result is still returned and marked with avoidanceUnmet.",
      "prefill": false,
      "title": "Avoid Ferries",
      "type": "boolean"
    },
    "avoidHighways": {
      "default": false,
      "description": "Driving only — ask Google Maps to avoid highways and motorways. If no practical alternative exists, Google may still return a highway route.",
      "prefill": false,
      "title": "Avoid Highways",
      "type": "boolean"
    },
    "avoidTolls": {
      "default": false,
      "description": "Driving only — ask Google Maps to avoid toll roads. If no toll-free route exists, Google may still return a toll route.",
      "prefill": false,
      "title": "Avoid Tolls",
      "type": "boolean"
    },
    "departureTime": {
      "description": "Optional ISO 8601 departure time as local time at the origin, for example 2026-06-16T10:30:00. Used for driving traffic estimates and transit schedules. A timezone offset is accepted but ignored; walking and bicycling ignore the field.",
      "editor": "textfield",
      "title": "Departure Time",
      "type": "string"
    },
    "destinations": {
      "description": "Ending locations for matrix mode. Each destination is paired with every origin above.",
      "editor": "stringList",
      "items": {
        "type": "string"
      },
      "prefill": [
        "Central Park, New York, NY",
        "Brooklyn Bridge, New York, NY",
        "JFK Airport, New York, NY"
      ],
      "title": "Destinations",
      "type": "array"
    },
    "directionsUrls": {
      "description": "Google Maps directions links for URLs mode. Canonical /maps/dir/ links and short share links are both accepted; waypoints and travel mode are read from the link when present.",
      "editor": "requestListSources",
      "items": {
        "properties": {
          "url": {
            "description": "Public Google Maps directions link.",
            "title": "URL",
            "type": "string"
          }
        },
        "required": [
          "url"
        ],
        "type": "object"
      },
      "title": "Directions URLs",
      "type": "array"
    },
    "includeSteps": {
      "default": true,
      "description": "Add turn-by-turn steps with instruction, distance, duration, maneuver, coordinates and route geometry for every returned route.",
      "prefill": false,
      "title": "Include Steps",
      "type": "boolean"
    },
    "includeStreetView": {
      "default": false,
      "description": "Add a Street View panorama ID and thumbnail URL to each step where Google publishes one. This also enables step details.",
      "prefill": false,
      "title": "Include Street View",
      "type": "boolean"
    },
    "language": {
      "default": "en",
      "description": "Language for instructions and other localized text.",
      "editor": "select",
      "enum": [
        "en",
        "es",
        "fr",
        "de",
        "it",
        "pt",
        "ja",
        "ko",
        "zh",
        "ar",
        "ru"
      ],
      "enumTitles": [
        "English",
        "Spanish",
        "French",
        "German",
        "Italian",
        "Portuguese",
        "Japanese",
        "Korean",
        "Chinese",
        "Arabic",
        "Russian"
      ],
      "prefill": "en",
      "title": "Language",
      "type": "string"
    },
    "maxAlternatives": {
      "default": 5,
      "description": "Maximum number of route alternatives to return per trip, including Google's recommended route. Applies to route and URLs modes. Google usually supplies up to 3 alternatives.",
      "editor": "number",
      "maximum": 8,
      "minimum": 1,
      "prefill": 1,
      "title": "Max Alternatives",
      "type": "integer"
    },
    "maxItems": {
      "default": 50,
      "description": "Global cap on the number of records pushed to the dataset.",
      "editor": "number",
      "maximum": 1000,
      "minimum": 1,
      "prefill": 5,
      "title": "Max Results",
      "type": "integer"
    },
    "maxPairs": {
      "default": 100,
      "description": "Maximum number of origin × destination pairs to request in matrix mode. Pairs beyond this cap are left out.",
      "editor": "number",
      "maximum": 1000,
      "minimum": 1,
      "prefill": 100,
      "title": "Max Pairs",
      "type": "integer"
    },
    "mode": {
      "default": "route",
      "description": "What to scrape: one route (with optional waypoints), a distance matrix, or a list of Google Maps directions URLs.",
      "editor": "select",
      "enum": [
        "route",
        "matrix",
        "urls"
      ],
      "enumTitles": [
        "Route — one trip, 2–10 stops",
        "Matrix — every origin × destination",
        "URLs — scrape directions links"
      ],
      "prefill": "route",
      "title": "Mode",
      "type": "string"
    },
    "origins": {
      "description": "Starting locations for matrix mode. Each origin is paired with every destination below.",
      "editor": "stringList",
      "items": {
        "type": "string"
      },
      "prefill": [
        "Times Square, New York, NY",
        "Grand Central Terminal, New York, NY"
      ],
      "title": "Origins",
      "type": "array"
    },
    "proxyConfiguration": {
      "description": "Optional fallback proxy. The actor first requests Google Maps directly and only retries through this proxy if the direct request is blocked.",
      "editor": "proxy",
      "title": "Proxy Configuration",
      "type": "object"
    },
    "requestDelayMs": {
      "default": 250,
      "description": "Pause between directions requests. A small delay keeps large matrix runs polite and reduces rate limiting.",
      "editor": "number",
      "maximum": 5000,
      "minimum": 0,
      "prefill": 250,
      "title": "Request Delay (ms)",
      "type": "integer"
    },
    "stops": {
      "description": "Ordered stops for route mode: 2–10 locations. The first is the origin, the last is the destination, and everything in between becomes a waypoint.",
      "editor": "stringList",
      "items": {
        "type": "string"
      },
      "maxItems": 10,
      "minItems": 2,
      "prefill": [
        "Times Square, New York, NY",
        "Central Park, New York, NY"
      ],
      "title": "Stops",
      "type": "array"
    },
    "travelMode": {
      "default": "driving",
      "description": "How to travel between the stops.",
      "editor": "select",
      "enum": [
        "driving",
        "walking",
        "bicycling",
        "transit"
      ],
      "enumTitles": [
        "Driving",
        "Walking",
        "Bicycling",
        "Public transit"
      ],
      "prefill": "driving",
      "title": "Travel Mode",
      "type": "string"
    },
    "units": {
      "default": "metric",
      "description": "Preferred distance units for the formatted distance fields. Meter values stay unchanged.",
      "editor": "select",
      "enum": [
        "metric",
        "imperial"
      ],
      "enumTitles": [
        "Metric (km, m)",
        "Imperial (mi, ft)"
      ],
      "prefill": "metric",
      "title": "Units",
      "type": "string"
    }
  },
  "schemaVersion": 1,
  "title": "Google Maps Directions Scraper",
  "type": "object"
}

Output schema

Published result links and storage locations. This schema is not an exhaustive contract for every field in a dataset record.

FieldTypeRequiredDescription
directionsstringoptionalDataset containing route, matrix and URL records. Each record contains one route alternative or one matrix row.

Download the published output schema

View complete JSON
{
  "actorOutputSchemaVersion": 1,
  "description": "Route, matrix and URL records from Google Maps directions — resolved stops, distance, duration, traffic, route alternatives, steps, geometry, transit lines and fares.",
  "properties": {
    "directions": {
      "description": "Dataset containing route, matrix and URL records. Each record contains one route alternative or one matrix row.",
      "template": "{{links.apiDefaultDatasetUrl}}/items",
      "title": "Directions records",
      "type": "string"
    }
  },
  "title": "Google Maps Route & Distance Matrix Scraper Output"
}

Dataset schema

Published dataset views and any declared field definitions. A view can select only a subset of the returned record fields.

Download the published dataset schema

View complete JSON
{
  "actorSpecification": 1,
  "views": {
    "matrix": {
      "display": {
        "component": "table",
        "properties": {}
      },
      "title": "Distance Matrix",
      "transformation": {
        "fields": [
          "recordType",
          "originIndex",
          "destinationIndex",
          "pairIndex",
          "origin",
          "destination",
          "originResolved",
          "destinationResolved",
          "travelMode",
          "distance",
          "distanceMeters",
          "duration",
          "durationSeconds",
          "durationInTraffic",
          "typicalDuration",
          "noTrafficDuration",
          "trafficRange",
          "routesAvailable",
          "googleMapsUrl",
          "scrapedAt"
        ]
      }
    },
    "overview": {
      "display": {
        "component": "table",
        "properties": {}
      },
      "title": "Directions",
      "transformation": {
        "fields": [
          "recordType",
          "origin",
          "destination",
          "originResolved",
          "destinationResolved",
          "routeName",
          "routeIndex",
          "isRecommended",
          "travelMode",
          "distance",
          "distanceMeters",
          "duration",
          "durationSeconds",
          "durationInTraffic",
          "typicalDuration",
          "noTrafficDuration",
          "trafficRange",
          "trafficCondition",
          "departureTime",
          "arrivalTime",
          "fare",
          "availableModes",
          "googleMapsUrl",
          "sourceUrl",
          "scrapedAt",
          "steps",
          "notes"
        ]
      }
    },
    "transit": {
      "display": {
        "component": "table",
        "properties": {}
      },
      "title": "Transit",
      "transformation": {
        "fields": [
          "origin",
          "destination",
          "routeIndex",
          "transitLine",
          "transitVehicle",
          "transitHeadsign",
          "departureTime",
          "arrivalTime",
          "duration",
          "fare",
          "transit",
          "googleMapsUrl",
          "scrapedAt"
        ]
      }
    }
  }
}

Key-value schema

Published key-value store definitions, when provided by this build.

This definition is not present in the default published build. See the published README for available documentation.

Published README

Read the full published documentation

Google Maps Route & Distance Matrix Scraper

Get Google Maps directions as structured data — route alternatives, multi-stop trips, turn-by-turn steps, live and typical traffic, transit lines and fares, Street View previews, and full origin × destination travel-time matrices. No Google API key, login or cookie is needed.

What this actor does

  • Route mode — one trip with 2–10 ordered stops. Middle stops become waypoints, just like Google Maps' "Add destination" feature.
  • Matrix mode — every origin × destination pair, one row per pair, with distance, duration and traffic estimates.
  • URLs mode — paste public Google Maps directions links, including canonical /maps/dir/... links and short share links.
  • Four travel modes — driving, walking, bicycling and public transit.
  • Route alternatives — Google's recommended route plus the alternatives it returns (usually up to 3); maxAlternatives caps the list at 1–8.
  • Turn-by-turn steps — instruction, distance, duration, maneuver, start/end coordinates, route geometry and optional Street View pano/thumbnail for every route, not just the first one.
  • Traffic detail — current duration, typical duration, no-traffic duration and the expected traffic range for driving routes.
  • Transit detail — line, vehicle, headsign, line colour, departure/arrival times, departure and arrival stops, intermediate stops, agency and fare when Google publishes it.
  • Departure planning — request driving or transit directions for a future departure time, expressed as local time at the origin.
  • Avoid flags — tolls, highways and ferries for driving routes.
  • Localized output — 11 instruction languages and metric or imperial distance formatting.

Fields are omitted when Google does not provide a value. The actor never fills a missing fare, ETA, instruction or coordinate with a guess.

Input

Field Type Default Description
mode select route route, matrix or urls
stops string list – Ordered stops for route mode (2–10); the prefill is Times Square → Central Park
origins string list – Matrix origins
destinations string list – Matrix destinations
directionsUrls request list – Google Maps directions links for URLs mode
maxPairs integer 100 Maximum matrix pairs (1–1000)
travelMode select driving driving, walking, bicycling or transit
avoidTolls boolean false Driving only
avoidHighways boolean false Driving only
avoidFerries boolean false Driving only
departureTime text – ISO 8601 datetime in the origin's local time; driving and transit
maxAlternatives integer 5 Route alternatives per trip (1–8)
maxItems integer 50 Global record cap (1–1000)
includeSteps boolean true Turn-by-turn steps and geometry
includeStreetView boolean false Street View pano ID and thumbnail per step
language select en Instruction language
units select metric metric or imperial formatting
requestDelayMs integer 250 Pause between requests (0–5000 ms)
proxyConfiguration proxy – Optional fallback; direct requests are tried first

Existing saved tasks that still send origin and destination keep working: the actor maps them to the first and last stop automatically.

Output: route records

Each route alternative becomes one record:

  • origin, destination, stops[], waypoints[] — your inputs plus Google's resolved names, addresses, coordinates and place IDs
  • originResolved, destinationResolved, originCoords, destinationCoords
  • recordType, routeIndex, routeName, routeSummary, isRecommended
  • distance, distanceMeters, distanceText — formatted distance, exact meters, and Google's original text
  • duration, durationSeconds, durationText
  • durationInTraffic, durationInTrafficSeconds
  • typicalDuration, typicalDurationSeconds, noTrafficDuration, noTrafficDurationSeconds, trafficRange, trafficRangeMinSeconds, trafficRangeMaxSeconds, trafficLevel, trafficCondition
  • via — the main road or highway
  • departureTime, arrivalTime, transitWindow, plus ISO timestamps and timezone for transit
  • fare, fares[], transit and transitSegments[] — line, vehicle, headsign, colour, stops, times and fare
  • steps[] — instruction, instruction parts, maneuver, distance, duration, start/end coordinates, Street View fields and notes
  • geometry[] — route geometry built from step coordinates
  • legs[] — per-leg distance, duration and step range for multi-stop trips
  • availableModes[] — Google's duration comparison for driving, walking, bicycling and transit
  • avoidanceUnmet[] — set when an avoidance request could not be honoured
  • notes[], googleMapsUrl, sourceUrl, inputUrl, scrapedAt

Output: matrix records

Matrix mode adds originIndex, destinationIndex, pairIndex and routesAvailable to the best route for each pair. recordType is matrix. maxPairs caps requested pairs and maxItems caps pushed rows.

Examples

Driving route with a waypoint

{
  "mode": "route",
  "stops": [
    "New York, NY",
    "Hartford, CT",
    "Boston, MA"
  ],
  "travelMode": "driving",
  "includeSteps": true
}

Transit trip with a future departure

{
  "mode": "route",
  "stops": ["Heathrow Airport, London", "British Museum, London"],
  "travelMode": "transit",
  "departureTime": "2026-11-06T13:00:00+00:00",
  "maxAlternatives": 6
}

Distance matrix

{
  "mode": "matrix",
  "origins": [
    "Warehouse A, Newark, NJ",
    "Warehouse B, Elizabeth, NJ"
  ],
  "destinations": [
    "10 Wall St, New York, NY",
    "20 Hudson Yards, New York, NY",
    "JFK Airport, Queens, NY"
  ],
  "travelMode": "driving",
  "maxPairs": 20,
  "maxItems": 20
}

Directions URLs

{
  "mode": "urls",
  "directionsUrls": [
    {"url": "https://www.google.com/maps/dir/Times+Square,+New+York,+NY/Central+Park,+New+York,+NY/?travelmode=driving"},
    {"url": "https://www.google.com/maps/dir/Heathrow+Airport,+London/British+Museum,+London/?travelmode=transit"}
  ],
  "maxAlternatives": 3
}

Use cases

  • Fleet dispatch and delivery-route planning
  • Commute and relocation comparisons across driving, walking, cycling and transit
  • Travel-time matrices for store, warehouse or service-area analysis
  • Itinerary planning with multi-stop road trips
  • Transit schedule and fare research

FAQ

How many alternatives can I get? maxAlternatives accepts 1–8 as a cap. Google's directions data usually provides up to 3 alternatives; the actor returns exactly what Google provides and never invents a route.

Do steps appear on every alternative? Yes. Every returned route contains its own steps, coordinates and geometry when includeSteps is on. Earlier versions only returned steps for the first route.

How does departure time handle timezones? departureTime is interpreted as the local clock time at the origin, matching Google Maps' "Depart at" control. An ISO 8601 offset is accepted but ignored, so 2026-11-06T13:00:00-05:00 and 2026-11-06T13:00:00 both mean 1 PM at the origin. Transit output also includes departureTimezone and ISO timestamps with the local offset.

Why is a fare or transit line missing from one route? Google only publishes fares and detailed line information for some transit agencies and routes. Those fields are omitted when absent instead of being estimated.

What happens when Google cannot avoid a toll, highway or ferry? Google may still return the only available route. In that case the record is kept and avoidanceUnmet explains which preference could not be met.

How large can a matrix be? maxPairs limits requested pairs (up to 1000) and maxItems limits pushed rows. For a matrix, one row is produced per pair, using Google's recommended route.

Do short share links work in URLs mode? Yes. Both full /maps/dir/... links and short Google Maps share links are resolved before scraping. Travel mode, waypoints and avoid preferences are read from the link when present.

Is an API key, cookie or login required? No. The actor reads the same public directions data Google Maps serves to a browser, without an account, cookie or API key.

Why do distances sometimes differ from Google's displayed text? Google localizes displayed units by country. The actor keeps the original text in distanceText and also converts the exact meter value into your selected units.

Is this affiliated with Google? No. This is an independent, third-party actor and is not affiliated with or endorsed by Google.

Python quickstart

Use a schema-derived input and the Python standard library to start a run. An Apify account and token are required for execution.

Open the step-by-step Python guide →

Source build rqVaq22Xv16eLhVf8. Documentation is regenerated from the default published build; private drafts are not included.