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:
Powered by Google, ©2022 Google
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:
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. Theroutes
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) } }