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. 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
      }
    }
  },
...
}

Note: The points specified by a latitude and longitude pair are snapped to roads and might not provide the accuracy your app needs. Use latitude and longitude coordinates when you are confident the values truly specify the points your app needs for routing without regard to possible access points or additional geocoding details.

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:

• Use location modifiers
• Use the vehicle stopover qualifier
• Specify intermediate waypoints

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