Specify locations for a route matrix

To calculate a route matrix, you must specify at a minimum the locations of one route origin and one route destination.

Specify locations for a route

You represent a location by creating a Waypoint (REST) or Waypoint (gRPC) object. In the waypoint definition, 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 ID for the destination waypoint.

For efficiency and accuracy, use place IDs 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 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/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 and 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, the Routes API geocodes both addresses to convert them to latitude and longitude coordinates.

If the address value is ambiguous, the 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.

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:

  • 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.