# Google Maps Route Matrix Scraper (`googleapi/google-maps-route-matrix-scraper`) Actor

Extract source-visible route choices, distance, duration, traffic advisories, tolls, transit options, and optional step directions from rendered public Google Maps pages.

- **URL**: https://apify.com/googleapi/google-maps-route-matrix-scraper.md
- **Developed by:** [Google API](https://apify.com/googleapi) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.99 / 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.

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

Compare route options for origin and destination pairs using public Google Maps directions pages. The Actor creates one dataset record per visible route option and supports driving, walking, cycling, transit, and other modes that Google Maps offers for the selected trip.

### How to use

Provide both `origins` and `destinations`, or supply public directions URLs in `startUrls`. Each origin is paired with each destination, within the configured limits.

```json
{
  "origins": ["New York, NY"],
  "destinations": ["White Plains, NY"],
  "travelMode": "driving",
  "units": "imperial",
  "includeAlternatives": true,
  "includeRouteText": true,
  "includeRouteSteps": false,
  "maxPairs": 25,
  "maxItems": 25
}
```

You can also start from a directions URL:

```json
{
  "startUrls": [
    { "url": "https://www.google.com/maps/dir/New+York,+NY/White+Plains,+NY" }
  ],
  "travelMode": "transit",
  "maxPairs": 5
}
```

### Input

| Input | Description | Default |
|---|---|---:|
| `origins` / `destinations` | Lists of start and end locations. Each origin is paired with each destination. | — |
| `startUrls` | Public Google Maps directions pages. `urls` is an alias. | — |
| `travelMode` | Requested travel mode. `mode` is an alias. | `driving` |
| `units` | Preferred distance units. The output preserves the units shown by Maps. | `metric` |
| `language` | Language for the directions page. | `en` |
| `includeAlternatives` | Include all visible route options for the requested mode. | `true` |
| `includeRouteText` | Include the route card text and displayed advisories. | `true` |
| `includeRouteSteps` | Collect optional step-by-step details for selected routes. | `false` |
| `maxDetailRoutes` | Maximum route options to enrich with steps. | 3 |
| `maxPairs` | Maximum origin-destination pairs to inspect. | 25 |
| `maxItems` | Maximum route records across the run. | 25 |
| `page` / `maxPages` | Starting point and number of pairs to inspect from the ordered pair list. | 1 / 10 |
| `proxyConfiguration` | Optional Apify Proxy settings. Direct connections are the default. | — |

### Output

Each dataset item represents a route option and includes route rank, origin, destination, travel mode, and the public Google Maps directions URL. When available, a record may also contain:

- Route name and visible route text.
- Distance and duration, with normalized numeric values.
- Google's displayed recommendation, traffic notes, warnings, avoided roads, and toll, closure, fastest-route, and traffic-recommendation details when available.
- Requested and observed travel modes, plus the other modes available for the trip.
- Transit details and the departure and arrival information shown by Maps.
- Step-by-step directions when `includeRouteSteps` is enabled and details are available.

The Actor reports only details shown for the selected route. It does not estimate traffic, infer tolls, or fill in missing steps. Optional step collection is limited by `maxDetailRoutes` and can increase run time.

Example dataset item:

```json
{
  "routeId": "route_123",
  "routeRank": 1,
  "routeOptionCount": 2,
  "isAlternative": false,
  "routeName": "Via I-87 N",
  "routeSummary": "31.2 mi · 45 min",
  "distance": { "text": "31.2 mi", "value": 31.2, "unit": "mi", "meters": 50211 },
  "duration": { "text": "45 min", "seconds": 2700 },
  "origin": { "input": "New York, NY" },
  "destination": { "input": "White Plains, NY" },
  "travelMode": "driving",
  "googleMapsUrl": "https://www.google.com/maps/dir/New+York,+NY/White+Plains,+NY"
}
```

Run summary information is available with the run output in Apify.

### Limits and responsible use

Available routes depend on Google Maps and the selected travel mode, time, and locale. The Actor does not sign in or bypass access checks. Use locations you are permitted to process and follow Google Maps terms and applicable laws. This Actor is not affiliated with Google.

# Changelog

This Actor's version history is a separate document: https://apify.com/googleapi/google-maps-route-matrix-scraper/changelog.md

# Actor input Schema

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

Starting locations. Pair each origin with every destination to form a bounded route matrix.

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

End locations paired with each origin.

## `startUrls` (type: `array`):

Optional public Google Maps directions pages. The actor reads the two visible endpoints and applies the selected travel mode, language, and units.

## `urls` (type: `array`):

Compatibility alias for startUrls. Use startUrls for new inputs.

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

Requested mode used to build the public directions page.

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

Compatibility alias for travelMode. If both are supplied they must match.

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

Preferred units sent with the directions request. The record preserves the unit Google actually displays.

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

Language code for the public directions page.

## `includeAlternatives` (type: `boolean`):

Return all observed route options for the requested travel mode instead of only the first option.

## `includeRouteText` (type: `boolean`):

Keep the visible route-card text, including the full advisory wording, in routeText.

## `includeRouteSteps` (type: `boolean`):

Select and expand each matched route's own public details, up to the global maxDetailRoutes cap. Retain base records when matching or details fail. Disabled by default.

## `maxDetailRoutes` (type: `integer`):

Global maximum number of route alternatives for which optional step-by-step pages may be fetched.

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

Maximum route pairs generated from the origin-destination matrix and start URLs.

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

Global cap on normal route records across all selected pairs.

## `page` (type: `integer`):

One-based starting position in the ordered origin-destination pair list.

## `maxPages` (type: `integer`):

Maximum number of origin-destination direction pages to inspect beginning at page. Each pair is one Google Maps directions page.

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

Pause between directions-page requests. A bounded exponential delay is also applied to transient retries.

## `maxRequestRetries` (type: `integer`):

Finite retries for network failures and server errors. Clear access boundaries are never retried.

## `requestTimeoutSecs` (type: `integer`):

Timeout for a public directions page request.

## `maxResponseBytes` (type: `integer`):

Upper bound on the visible rendered page text collected from each Google Maps directions page.

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

Optional Apify Proxy or custom proxy editor settings used for all rendered Playwright browser requests. Direct connections remain the default. A proxy does not bypass access challenges.

## Actor input object example

```json
{
  "travelMode": "driving",
  "units": "metric",
  "language": "en",
  "includeAlternatives": true,
  "includeRouteText": true,
  "includeRouteSteps": false,
  "maxDetailRoutes": 3,
  "maxPairs": 25,
  "maxItems": 25,
  "page": 1,
  "maxPages": 10,
  "requestDelayMs": 250,
  "maxRequestRetries": 1,
  "requestTimeoutSecs": 30,
  "maxResponseBytes": 5000000,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `dataset` (type: `string`):

No description

## `runSummary` (type: `string`):

No description

## `runHealth` (type: `string`):

No description

# 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("googleapi/google-maps-route-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 = {}

# Run the Actor and wait for it to finish
run = client.actor("googleapi/google-maps-route-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 '{}' |
apify call googleapi/google-maps-route-matrix-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,googleapi/google-maps-route-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/hj26VxbiKkSzEdaHE/builds/mnRyfwVOA0b5flfOC/openapi.json