Get a route

A route is a navigable path between a start location, or origin, and an end location, or destination. You can choose to get a route for different modes of transportation, such as walking, biking, or different types of vehicles. You can also request route details such as distance, estimated time to navigate the route, expected tolls, and step-by-step instructions to navigate the route.

Call the computeRoutes() method to request a route between two locations. The following example shows defining a request and then calling computeRoutes() to get a route. 

  // Import the Routes library.
  const { Route } = await google.maps.importLibrary('routes');

  // Define a computeRoutes request.
  const request = {
    origin: 'Mountain View, CA',
    destination: 'San Francisco, CA',
  };

  // Call the computeRoutes() method to get routes.
  const {routes} = await Route.computeRoutes(request);

Choose fields to return

When you request a route, you must use a field mask to specify what information the response should return. You can specify the names of the Route class properties in the field mask.

Using a field mask also ensures that you don't request unnecessary data, which in turn helps with response latency and avoids returning information your system doesn't need.

Specify the list of fields you need by setting the ComputeRoutesRequest.fields property, as shown in the following snippet: 

// Define a routes request.
const request = {
  origin: 'Mountain View, CA',
  destination: 'San Francisco, CA',
  fields: ['path'], // Request fields needed to draw polylines.
};

Specify locations for a route

To calculate a route, you must specify at a minimum the locations of the route origin and route destination, and a field mask. You can also specify intermediate waypoints along a route, and use waypoints to do other things like adding stops or passthrough points along a route.

In the ComputeRoutesRequest, you can specify a location in any of the following ways:

You can specify locations for all waypoints in a request the same way, or you can mix them. For example, you can use latitude/longitude coordinates for the origin waypoint and use a Place object for the destination waypoint.

For efficiency and accuracy, use Place objects instead of latitude/longitude coordinates or address strings. Place IDs are uniquely explicit and provide geocoding benefits for routing such as access points and traffic variables. They help avoid the following situations that can result from other ways of specifying a location:

  • Using latitude/longitude coordinates can result in the location being snapped to the road nearest to those coordinates - which might not be an access point to the property, or even a road that quickly or safely leads to the destination.
  • Address strings must first be geocoded by the Routes API to convert them to latitude/longitude coordinates before it can calculate a route. This conversion can affect performance.

Specify a location as a Place object (preferred)

To specify a location using a Place, create a new Place instance. The following snippet shows creating new Place instances for origin and destination, and then using them in a ComputeRoutesRequest: 

// Create a new Place for the origin.
const originPlace = new Place({
  id: 'ChIJiQHsW0m3j4ARm69rRkrUF3w', // Mountain View, CA
});

// Create a new Place for the destination.
const destinationPlace = new Place({
  id: 'ChIJIQBpAG2ahYAR_6128GcTUEo', // San Francisco, CA
});

// Define a computeRoutes request.
const request = {
  origin: originPlace,
  destination: destinationPlace,
  fields: ['path'],
};

Latitude/longitude coordinates

To specify a location as latitude/longitude coordinates, create either a new google.maps.LatLngLiteral, google.maps.LatLngAltitude, or google.maps.LatLngAltitudeLiteral instance. The following snippet shows creating new google.maps.LatLngLiteral instances for origin and destination, and then using them in a computeRoutesRequest: 

// Create new LatLngLiteral objects for the origin and destination.
// Mountain View, CA
const originLatLng = {lat: 37.422000, lng: -122.084058};
// San Francisco, CA
const destinationLatLng = {lat: 37.774929, lng: -122.419415};

// Define a computeRoutes request.
const request = {
  origin: originLatLng,
  destination: destinationLatLng,
  fields: ['path'],
};

Address string

Address strings are literal addresses represented by a string (such as "1600 Amphitheatre Parkway, Mountain View, CA"). Geocoding is the process of converting an address string into latitudes and longitude coordinates (such as latitude 37.423021 and longitude -122.083739).

When you pass an address string as the location of a waypoint, the Routes library internally geocodes the string to convert it to latitude and longitude coordinates.

The following snippet shows creating a ComputeRoutesRequest with an address string for origin and destination: 

// Define a computeRoutes request.
const request = {
  origin: '1600 Amphitheatre Parkway, Mountain View, CA',
  destination: '345 Spear Street, San Francisco, CA',
  fields: ['path'],
};

Set the region for the address

If you pass an incomplete address string as the location of a waypoint, the API might use the wrong geocoded latitude/longitude coordinates. For example, you make a request specifying "Toledo" as the origin and "Madrid" as the destination for a driving route: 

// Define a request with an incomplete address string.
const request = {
  origin: 'Toledo',
  destination: 'Madrid',
};

In this example, "Toledo" is interpreted as a city in the state of Ohio in the United States, not in Spain. Therefore, the request returns an empty array, meaning no routes exist.

You can configure the API to return results biased to a particular region by including the regionCode parameter. This parameter specifies the region code as a ccTLD ("top-level domain") two-character value. Most ccTLD codes are identical to ISO 3166-1 codes, with some notable exceptions. For example, the United Kingdom's ccTLD is "uk" (.co.uk) while its ISO 3166-1 code is "gb" (technically for the entity of "The United Kingdom of Great Britain and Northern Ireland").

A directions request for "Toledo" to "Madrid" that includes the regionCode parameter returns appropriate results because "Toledo" is interpreted as a city in Spain:

const request = {
  origin: 'Toledo',
  destination: 'Madrid',
  region: 'es', // Specify the region code for Spain.
};

Plus Code

Many people don't have a precise address, which can make it difficult for them to receive deliveries. Or, people with an address might prefer to accept deliveries at more specific locations, such as a back entrance or a loading dock.

Plus Codes are like street addresses for people or places that don't have an actual address. Instead of addresses with street names and numbers, Plus Codes are based on latitude/longitude coordinates, and are displayed as numbers and letters.

Google developed Plus Codes to give the benefit of addresses to everyone and everything. A Plus Code is an encoded location reference, derived from latitude/longitude coordinates, that represents an area: 1/8000th of a degree by 1/8000th of a degree (about 14m x 14m at the equator) or smaller. You can use Plus Codes as a replacement for street addresses in places where they don't exist or where buildings are not numbered or streets are not named.

Plus Codes must be formatted as a global code or a compound code:

  • global code is composed of a 4 character area code and 6 character or longer local code. For example, for the address "1600 Amphitheatre Parkway, Mountain View, CA", the global code is "849V" and the local code is "CWC8+R9". You then use the entire 10 character Plus Code to specify the location value as "849VCWC8+R9".
  • compound code is composed of a 6 character or longer local code combined with an explicit location. For example, the address "450 Serra Mall, Stanford, CA 94305, USA" has a local code of "CRHJ+C3". For a compound address, combine the local code with the city, state, ZIP code, and country portion of the address in the form "CRHJ+C3 Stanford, CA 94305, USA".

The following snippet shows calculating a route by specifying a waypoint for the route origin and destination using Plus Codes: 

const request = {
  origin: '849VCWC8+R9', // Mountain View, CA
  destination: 'CRHJ+C3 Stanford, CA 94305, USA', // Stanford, CA
  fields: ['path'],
};