The Routes API is currently in Preview (pre-GA). Pre-GA products and features might have limited support, and changes to pre-GA products and features might not be compatible with other pre-GA versions. Pre-GA Offerings are covered by the Google Maps Platform Service Specific Terms. For more information, see the launch stage descriptions.

Specify location and route options

Stay organized with collections Save and categorize content based on your preferences.

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. To define a waypoint, you specify the geographic Location (REST) or Location (gRPC) as a latitude and longitude pair.

For example, to calculate a route, specify a waypoint for the route origin and destination as a latitude and longitude pair:

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

Alternatively, you can use a place ID to specify either the origin or destination. Because a latitude and longitude pair 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"
  },
  ...
}

For a route matrix, specify one or more waypoints to the origins and destinations arrays as a latitude and longitude pair or as a place ID:

{
  "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,
    }}}
  }],
...
}

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

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

See RouteTravelMode.

Routing preference Whether to take traffic conditions into consideration. See RoutingPreference.
Departure time Specify the time of departure.
Route modifiers Specify options such as to avoid tolls, avoid highways, and other options. See RouteModifiers.
Language code The language code for the returned response (Compute Routes only).
Units The units of measure in the response (Compute Routes) only).