Routes API Overview

The Routes API is a service that accepts an HTTPS request and returns either the ideal route between two locations, or distances and travel times for a matrix of routes between different origin and destination locations.

Why use the Routes API

With the Routes API, you can get accurate routes and trip information using transport details, up-to-date traffic and road conditions, and route preferences:

  • Type and capabilities of different modes of transport

  • Which direction a vehicle is headed

  • The side of the road for pick ups or drop offs

  • Traffic conditions and road closures

  • Safety concerns such as avoiding dangerous areas or providing safe pickup areas

  • Balance latency, quality, and cost across your routing needs with optional features such as tolls and trip metadata such as time and distance, and fuel efficiency

You can also determine the most efficient routes for dispatch scheduling, such as:

  • How best to assign a set of workers to pick up a series of packages

  • Determine the best warehouse from which to ship packages to their final destination

What you can do with the Routes API?

With the Routes API, you can get two primary categories of routing information:

  • Routes from a location to a single or multiple destinations

  • A matrix of possible routes between many start and end locations.

Get routes for single or multiple destinations

With the Routes API Compute Routes method, you can calculate between locations:

  • Get directions for different ways to travel, and for a single or multiple destinations:

    • Modes of transportation, including transit, driving, two-wheel vehicles, walking or bicycling.

    • A series of waypoints, that you can optimize for the most efficient order to travel them in.

  • Multiple ways to specify origins, destinations, and waypoints:

    • Text strings. For example: "Chicago, IL", "Darwin, NT, Australia", "1800 Amphitheatre Parkway, Mountain View, CA 94043", or "CWF6+FWX Mountain View, California"

    • Place IDs

    • Latitude and longitude coordinates, optionally with vehicle heading

  • Fine-tune your route options based on your needs and goals:

  • Control your latency and quality by requesting only the data you need using a field mask, which helps you avoid unnecessary processing time and higher request billing rates. For details, see Choose what information to return.

Get a matrix of possible routes

The Routes API Compute Route Matrix method provides a matrix of information for recommended routes between multiple start and end points, including distance and estimated arrival times, to help you choose the best origins and destinations based on your business needs. You can request these kinds of distance data:

  • Distance for a selected travel mode

  • Distance in kilometers or miles

  • Estimated travel time in traffic

With the distance data, you can determine the most efficient way to route passengers, shipments, or workers between multiple possible origins and destinations.

You can stream elements of the response before the entire matrix has been calculated, lowering response latency.

You can specify multiple origins and destinations per server-side request with the number of origins times the number of destinations up to 625.

How the Routes API works

The Routes API has two methods: ComputeRoute and ComputeRouteMatrix.

ComputeRoute

The Routes API ComputeRoute method accepts an HTTP POST request with a JSON request body that contains the request details. Required are an origin, destination, travelMode, and a field mask to specify which fields to return.

Example

curl -X POST -d '{
    "origin": {
      "address": "1800 Amphitheatre Parkway, Mountain View, CA 94043"
    },
    "destination": {
      "address": "Sloat Blvd &, Upper Great Hwy, San Francisco, CA 94132"
    },
  "travelMode": "DRIVE"
  }' \
  -H 'Content-Type: application/json' -H 'X-Goog-Api-Key: YOUR_API_KEY' \
  -H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters' \
  'https://routes.googleapis.com/directions/v2:computeRoutes'

The service then calculates the requested route, and returns the fields you've requested.

ComputeRouteMatrix

The Routes API ComputeRouteMatrix accepts an HTTP POST request with a JSON request body that contains the request details. Required are at least one origin, two or more destinations, travelMode, and a field mask to specify which fields to return.

Example

curl -X POST -d '{
  "origins": [
    {
      "waypoint": {
        "location": {
          "latLng": {
            "latitude": 37.420761,
            "longitude": -122.081356
          }
        }
      }
    },
    {
      "waypoint": {
        "location": {
          "latLng": {
            "latitude": 37.403184,
            "longitude": -122.097371
          }
        }
      }
    }
  ],
  "destinations": [
    {
      "waypoint": {
        "location": {
          "latLng": {
            "latitude": 37.420999,
            "longitude": -122.086894
          }
        }
      }
    },
    {
      "waypoint": {
        "location": {
          "latLng": {
            "latitude": 37.383047,
            "longitude": -122.044651
          }
        }
      }
    }
  ],
  "travelMode": "DRIVE"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: originIndex,destinationIndex,duration,distanceMeters,status,condition' \
'https://routes.googleapis.com/distanceMatrix/v2:computeRouteMatrix'

The response contains the possible routes for the combination of all origin and destination waypoints.

Resources

The following table summarizes the resources available through the Routes API along with the data it returns.

Data resources Data returned Return format
ComputeRoute Returns routes, legs, and steps for a route, with alternate routes, if requested. JSON
ComputeRouteMatrix Returns an array of routes from one origin waypoint to one destination waypoint.

How to use the Routes API

1 Get set up Start with Set up your Google Cloud project and complete the setup instructions that follow.
2 Compute a route and review the response For more information, see Get a route and Review the route responses.
3 Compute matrix of routes and review the response For more information, see Get a route matrix and Review the route matrix response.

Available client libraries

For a list of the available client libraries for the Routes API, see Client libraries.

What's next