Specify location and route options

To calculate a route or a route matrix, you must specify at a minimum the location of the route origin and the location of the route destination. Define each location as a waypoint on the route.

Along with the location, you can specify many different options to control the route. For example, you can specify to avoid tolls or that the route is for walking or for a two-wheeled vehicle.

Specify a location

For the Routes API, you represent a location by creating a Waypoint (REST) or Waypoint (gRPC) object. In the waypoint definition, specify a location by using:

Place IDs
Latitude/longitude coordinates
Address strings ("Chicago, IL" or "Darwin, NT, Australia")
Plus Codes

You can use the same location representation for all waypoints in a request, or mix them. For example, you can use latitude/longitude coordinates for the origin waypoint and use a place ID for the destination waypoint.

Using place IDs is preferred over using latitude/longitude coordinates or address strings:

Using latitude/longitude coordinates results 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 will quickly or safely lead to the destination.
Address strings are often how a user inputs an address. However, Routes API must first geocode the address string internally to convert it to latitude/longitude coordinates before it can calculate a route. This conversion can affect performance.

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 and longitude, and are displayed as numbers and letters.

The Routes API provides many options for you to create waypoints. For more information and examples on waypoints, see:

Specify a location as a place ID

You can use a place ID to specify the location of a waypoint. Because latitude and longitude coordinates are snapped to roads, you might find a place ID offers better results in some circumstances.

Retrieve place IDs from the Geocoding API and the Places API (including Place Autocomplete). For more about place IDs, see the Place ID overview.

The following example uses the placeId property to pass a place ID for both the origin and destination:

{
  "origin":{
    "placeId": "ChIJayOTViHY5okRRoq2kGnGg8o"
  },
  "destination":{
    "placeId": "ChIJTYKK2G3X5okRgP7BZvPQ2FU"
  },
  ...
}

Specify a location as latitude and longitude coordinates

To define location in a waypoint, specify the Location (REST) or Location (gRPC) by using latitude and longitude coordinates.

For example, specify a waypoint for the route origin and destination using latitude and longitude coordinates:

{
  "origin":{
    "location":{
      "latLng":{
        "latitude": 37.419734,
        "longitude": -122.0827784
      }
    }
  },
  "destination":{
    "location":{
      "latLng":{
        "latitude": 37.417670,
        "longitude": -122.079595
      }
    }
  },
...
}

Specify a location as an 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, Routes API internally geocodes the string to convert it to latitude/longitude coordinates.

For example, to calculate a route you specify a waypoint for the route origin and destination using address strings:

{
  "origin":{
    "address": "1600 Amphitheatre Parkway, Mountain View, CA"
  },
  "destination":{
    "address": "450 Serra Mall, Stanford, CA 94305, USA"
  },
  ...
}

In this example, Routes API geocodes both addresses to convert them to latitude/longitude coordinates.

If the address value is ambiguous, Routes API might invoke a search to disambiguate from similar addresses. For example, "1st Street" could be a complete value or a partial value for "1st street NE" or "1st St SE". This result may be different from that returned by the Geocoding API. You can avoid possible misinterpretations using place IDs.

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:

{
  "origin":{
    "address": "Toledo"
  },
  "destination":{
    "address": "Madrid"
  },
  "travelMode": "DRIVE"
}

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 exists:

{
  []
}

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:

{
  "origin":{
    "address": "Toledo"
  },
  "destination":{
    "address": "Madrid"
  },
  "travelMode": "DRIVE",
  "regionCode": "es"
}

The response now contains the route calculated from Toledo, Spain to Madrid, Spain:

{
  "routes": [
    {
      "distanceMeters": 75330,
      "duration": "4137s",
      ...
    }
  ]
}

Specify a location as a 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.

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 and 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 do not 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:

A 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".
A 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".

For example, calculate a route by specifying a waypoint for the route origin and destination using Plus Codes:

{
  "origin":{
    "address": "849VCWC8+R9"
  },
  "destination":{
    "address": "CRHJ+C3 Stanford, CA 94305, USA"
  },
  "travelMode": "DRIVE"
}

Plus Codes are supported in Google Maps Platform APIs including Place Autocomplete, Place Details, Directions API and Geocoding API. For example, you can use Geocoding API to reverse geocoding a location specified by latitude/longitude coordinates to determine the location's Plus Code.

Specify route options

Along with specifying the origin and destination, you can specify many options to control the route. The following table lists these options:

Option	Description
Travel mode	The mode of travel, such as drive, bicycle, walk, or two-wheel vehicle. Note: Walking, bicycling, and two-wheel routes are in beta and might sometimes be missing clear sidewalks, pedestrian paths, or bicycling paths. You must display this warning to the user for all walking, bicycling, and two-wheel routes that you display in your app. See Route two-wheeled vehicles and RouteTravelMode.
Configure route quality vs latency	Whether to take traffic conditions into consideration. See Configure quality vs latency.
Route modifiers	Specify options to avoid tolls, avoid highways, and other options. See Configure route modifiers.
Calculate toll fees	Estimate any toll fees for a route. See Calculate toll fees.
Configure eco-friendly routes	Compute an eco-friendly route showing the most fuel- or energy-efficient route based on your vehicle's engine type. See Configure eco-friendly routes.
Request alternative routes	Compute up to three alternative routes along with the default route. See Request alternative routes.
Additional options	Specify additional options, such as the departure time, the language code for the returned response (Compute Routes only), and the units of measure in the response (Compute Routes) only). See Request body.