Understand the compute route response

To compute a route, the Routes API takes a list of waypoints and configuration parameters as input. The API then returns a response that contains the default route and one or more optional routes.

The request to compute a route supports many input options. For example, you can request:

The eco-friendly route for the most fuel or energy efficient route based on the vehicle's engine type.
Up to three alternative routes.
The traffic-aware polyline for an entire route or for each leg of a route.
The estimated tolls, taking into consideration any toll price discounts or passes available to the driver or vehicle.
Many other options. For the complete list of input options, see the Request body.

Using the response, you can provide your customers with the information necessary to select the appropriate route for their requirements.

About field masks

When you call a method to compute a route, you must specify a field mask that defines which fields you want returned in the response. There is no default list of returned fields. If you omit this list, the methods return an error.

The examples in this document show the entire response object without taking field masks into consideration. In a production environment, your response would only include the fields that you explicitly specify in the field mask.

For more information, see Choose fields to return.

About displaying copyrights

You must include the following copyright statement when displaying the results to your users:

Powered by Google, ©YEAR Google

For example:

About routes, legs, and steps

Before looking at the response returned by the Routes API, you should have an understanding of the components that make up a route:

The route, leg, and step.

Where:

Route: The entire trip from the origin waypoint, through any intermediate waypoints, to the destination waypoint. A route consists of one or more legs.
Leg: The path from one waypoint in a route to the next waypoint in the route. Each leg consists of one or more discrete steps.

A route contains a separate leg for the path from each waypoint to the next. For example, if the route contains a single origin waypoint and a single destination waypoint, then the route contains a single leg. For each additional waypoint you add to the route after the origin and destination, called an intermediate waypoint, the API adds a separate leg.

The API does not add a leg for a pass-through intermediate waypoint. For example, a route that contains an origin waypoint, a pass-through intermediate waypoint, and a destination waypoint contains just one leg from the origin to the destination, while passing through the waypoint. For more information on pass-through waypoints, see Define a pass-through waypoint.
Step: A single instruction along the leg of a route. A step is the most atomic unit of a route. For example, a step can indicate "Turn left on Main Street''.

About the response

The JSON object representing the API response contains two top-level properties:

routes, an array of elements of type Route. The routes array contains one element for each route returned by the API. The array can contain a maximum of five elements: the default route, the eco-friendly route, and up to three alternative routes.
fallbackInfo, of type FallbackInfo. If the API is not able to compute a route from all of the input properties, it might fallback to using a different way of computation. When fallback mode is used, this field contains detailed info about the fallback response. Otherwise this field is unset.

The response has the form:

{
  // The routes array.
  "routes": [
    {
      object (Route)
    }
  ],
  // The fallback property.
  "fallbackInfo": {
    object (FallbackInfo)
  }
}

Understand the routes array

The response contains the routes array, where each array element is of type Route. Each array element represents an entire route from origin to destination. The API always returns at least one route, called the default route.

You can request additional routes. If you request an eco-friendly route, then the array can contain two elements: the default route and the eco-friendly route. Or, set computeAlternativeRoutes to true in the request to add up to three alternative routes to the response.

Identify each route in the array by using the routeLabels array property. The routeLabels array property contains:

Value	Description
`DEFAULT_ROUTE`	Identifies the default route.
`FUEL_EFFICIENT`	Identifies the eco-friendly route.
`DEFAULT_ROUTE_ALTERNATE`	Indicates an alternative route.

The legs array contains the definition of each leg of the route. The remaining properties, such as distanceMeters, duration, and polyline, contain information about the route as a whole:

{
  "routeLabels": [
    enum (RouteLabel)
  ],
  "legs": [
    {
      object (RouteLeg)
    }
  ],
  "distanceMeters": integer,
  "duration": string,
  "routeLabels": [string],
  "staticDuration": string,
  "polyline": {
    object (Polyline)
  },
  "description": string,
  "warnings": [
    string
  ],
  "viewport": {
    object (Viewport)
  },
  "travelAdvisory": {
    object (RouteTravelAdvisory)
  }
  "routeToken": string
}

Because of current driving conditions and other factors, the default route and the eco-friendly route can be the same. In this case, routeLabels array contains both labels: DEFAULT_ROUTE and FUEL_EFFICIENT.

{
  "routes": [
    {
      "routeLabels": [
        "DEFAULT_ROUTE",
        "FUEL_EFFICIENT"
      ],
     …
    }
  ]
}

Understand the legs array

Each route in the response contains a legs array, where each legs array element is of type RouteLeg. Each leg in the array defines the path from one waypoint to the next waypoint along the route. A route always contains at least one leg.

The legs property contains the definition of each step along the leg in the steps array. The remaining properties, such as distanceMeters, duration, and polyline contain information about the leg.

{
  "distanceMeters": integer,
  "duration": string,
  "staticDuration": string,
  "polyline": {
    object (Polyline)
  },
  "startLocation": {
    object (Location)
  },
  "endLocation": {
    object (Location)
  },
  "steps": [
    {
      object (RouteLegStep)
    }
  ],
  "travelAdvisory": {
    object (RouteLegTravelAdvisory)
  }
}

Understand the steps array

Each leg in the response contains a steps array, where each steps array element is of type RouteLegStep. A step corresponds to a single instruction along the leg. A leg always contains at least one step.

Each element in the steps array includes the navigationInstruction property, of type NavigationInstruction, which contains the step instruction. For example:

"navigationInstruction": {
  "maneuver": "TURN_LEFT",
  "instructions": "Turn left toward Frontage Rd"
}

The instructions might contain additional information about the step. For example:

"navigationInstruction": {
  "maneuver": "TURN_SLIGHT_LEFT",
  "instructions": "Slight left (signs for I-90 W/Worcester)nParts of this road may be closed at certain times or days"
}

The remaining properties in the step describe information about the step, such as distanceMeters, duration, and polyline:

{
  "distanceMeters": integer,
  "staticDuration": string,
  "polyline": {
    object (Polyline)
  },
  "startLocation": {
    object (Location)
  },
  "endLocation": {
    object (Location)
  },
  "navigationInstruction": {
    object (NavigationInstruction)
  },
  "travelAdvisory": {
    object (RouteLegStepTravelAdvisory)
  }
}