# Google Maps Route & Distance Matrix Scraper (`vexaloom-labs/google-maps-route-and-distance-matrix-scraper`) Actor

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.

- **URL**: https://apify.com/vexaloom-labs/google-maps-route-and-distance-matrix-scraper.md
- **Developed by:** [vexaloom-labs](https://apify.com/vexaloom-labs) (community)
- **Categories:** Automation, Developer tools, Travel
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.49 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## 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

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

#### Transit trip with a future departure

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

#### Distance matrix

```json
{
  "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

```json
{
  "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.

# Actor input Schema

## `mode` (type: `string`):

What to scrape: one route (with optional waypoints), a distance matrix, or a list of Google Maps directions URLs.

## `stops` (type: `array`):

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.

## `origins` (type: `array`):

Starting locations for matrix mode. Each origin is paired with every destination below.

## `destinations` (type: `array`):

Ending locations for matrix mode. Each destination is paired with every origin above.

## `directionsUrls` (type: `array`):

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.

## `maxPairs` (type: `integer`):

Maximum number of origin × destination pairs to request in matrix mode. Pairs beyond this cap are left out.

## `travelMode` (type: `string`):

How to travel between the stops.

## `avoidTolls` (type: `boolean`):

Driving only — ask Google Maps to avoid toll roads. If no toll-free route exists, Google may still return a toll route.

## `avoidHighways` (type: `boolean`):

Driving only — ask Google Maps to avoid highways and motorways. If no practical alternative exists, Google may still return a highway route.

## `avoidFerries` (type: `boolean`):

Driving only — prefer routes without ferry crossings. If every route uses a ferry, the result is still returned and marked with avoidanceUnmet.

## `departureTime` (type: `string`):

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.

## `maxAlternatives` (type: `integer`):

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.

## `maxItems` (type: `integer`):

Global cap on the number of records pushed to the dataset.

## `includeSteps` (type: `boolean`):

Add turn-by-turn steps with instruction, distance, duration, maneuver, coordinates and route geometry for every returned route.

## `includeStreetView` (type: `boolean`):

Add a Street View panorama ID and thumbnail URL to each step where Google publishes one. This also enables step details.

## `language` (type: `string`):

Language for instructions and other localized text.

## `units` (type: `string`):

Preferred distance units for the formatted distance fields. Meter values stay unchanged.

## `requestDelayMs` (type: `integer`):

Pause between directions requests. A small delay keeps large matrix runs polite and reduces rate limiting.

## `proxyConfiguration` (type: `object`):

Optional fallback proxy. The actor first requests Google Maps directly and only retries through this proxy if the direct request is blocked.

## Actor input object example

```json
{
  "mode": "route",
  "stops": [
    "Times Square, New York, NY",
    "Central Park, New York, NY"
  ],
  "origins": [
    "Times Square, New York, NY",
    "Grand Central Terminal, New York, NY"
  ],
  "destinations": [
    "Central Park, New York, NY",
    "Brooklyn Bridge, New York, NY",
    "JFK Airport, New York, NY"
  ],
  "maxPairs": 100,
  "travelMode": "driving",
  "avoidTolls": false,
  "avoidHighways": false,
  "avoidFerries": false,
  "maxAlternatives": 1,
  "maxItems": 5,
  "includeSteps": true,
  "includeStreetView": false,
  "language": "en",
  "units": "metric",
  "requestDelayMs": 250
}
```

# Actor output Schema

## `directions` (type: `string`):

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

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "mode": "route",
    "stops": [
        "Times Square, New York, NY",
        "Central Park, New York, NY"
    ],
    "origins": [
        "Times Square, New York, NY",
        "Grand Central Terminal, New York, NY"
    ],
    "destinations": [
        "Central Park, New York, NY",
        "Brooklyn Bridge, New York, NY",
        "JFK Airport, New York, NY"
    ],
    "maxPairs": 100,
    "travelMode": "driving",
    "avoidTolls": false,
    "avoidHighways": false,
    "avoidFerries": false,
    "maxAlternatives": 1,
    "maxItems": 5,
    "includeSteps": false,
    "includeStreetView": false,
    "language": "en",
    "units": "metric",
    "requestDelayMs": 250
};

// Run the Actor and wait for it to finish
const run = await client.actor("vexaloom-labs/google-maps-route-and-distance-matrix-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "mode": "route",
    "stops": [
        "Times Square, New York, NY",
        "Central Park, New York, NY",
    ],
    "origins": [
        "Times Square, New York, NY",
        "Grand Central Terminal, New York, NY",
    ],
    "destinations": [
        "Central Park, New York, NY",
        "Brooklyn Bridge, New York, NY",
        "JFK Airport, New York, NY",
    ],
    "maxPairs": 100,
    "travelMode": "driving",
    "avoidTolls": False,
    "avoidHighways": False,
    "avoidFerries": False,
    "maxAlternatives": 1,
    "maxItems": 5,
    "includeSteps": False,
    "includeStreetView": False,
    "language": "en",
    "units": "metric",
    "requestDelayMs": 250,
}

# Run the Actor and wait for it to finish
run = client.actor("vexaloom-labs/google-maps-route-and-distance-matrix-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "mode": "route",
  "stops": [
    "Times Square, New York, NY",
    "Central Park, New York, NY"
  ],
  "origins": [
    "Times Square, New York, NY",
    "Grand Central Terminal, New York, NY"
  ],
  "destinations": [
    "Central Park, New York, NY",
    "Brooklyn Bridge, New York, NY",
    "JFK Airport, New York, NY"
  ],
  "maxPairs": 100,
  "travelMode": "driving",
  "avoidTolls": false,
  "avoidHighways": false,
  "avoidFerries": false,
  "maxAlternatives": 1,
  "maxItems": 5,
  "includeSteps": false,
  "includeStreetView": false,
  "language": "en",
  "units": "metric",
  "requestDelayMs": 250
}' |
apify call vexaloom-labs/google-maps-route-and-distance-matrix-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,vexaloom-labs/google-maps-route-and-distance-matrix-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/nsNiNL5MalNOLsSyK/builds/rqVaq22Xv16eLhVf8/openapi.json