Review the route response

When the Routes API computes a route, it takes the waypoints and configuration parameters you provide as input. The API then returns a response that contains the default route and one or more alternative routes.

Your response can include different types of routes and other data, based on the fields you request:

To include this in the response	See this documentation
The most fuel or energy efficient route based on the vehicle's engine type.	Configure Eco-friendly routes
Up to three alternative routes	Request alternate routes
The polyline for an entire route, for each leg of a route, and for each step of a leg.	Request route polylines
The estimated tolls, taking into consideration any toll price discounts or passes available to the driver or vehicle.	Calculate toll fees
Localized responses by language codes and measurement unit (imperial or metric).	Request localized values
To format the navigation instructions as an HTML text string, add HTML_FORMATTED_NAVIGATION_INSTRUCTIONS to extraComputations.	Extra Computations

For the complete list of input options, see Available route options and the Request body.

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

Note: To get a better idea of how the API handles different types of route requests, Try the demo. The demo lets you enter addresses and then view the response as visualized content.

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 what information 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, ©2023 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:

Your response may contain information about each of these route components:

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

What's in the response

The JSON object representing the API response contains the following 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.

• geocodingResults, an array of elements of type GeocodingResults. For every location in the request (origin, destination, or intermediate waypoint) that you specified as an address string or as a Plus code, the API performs a place ID lookup. Each element of this array contains the place ID corresponding to a location. Locations in the request specified as a place ID or as latitude/longitude coordinates are not included. If you've specified all locations using place IDs or latitude and longitude coordinates, this array is not provided.

• 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 place ID lookup results.
  "geocodingResults": [
    {
      object (GeocodedWaypoint)
    }
  ],
  // The fallback property.
  "fallbackInfo": {
    object (FallbackInfo)
  }
}

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

Each route in the array is identified with the routeLabels array property:

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

Specify the language of the step instructions

The API returns route information in the local language, transliterated to a script readable by the user, if necessary, while observing the preferred language. Address components are all returned in the same language.

• Use the languageCode parameter of a request to explicitly set the route language from the list of supported languages. Google often updates the supported languages, so this list may not be exhaustive.

• If a name is not available in the specified language, the API uses the closest match.

• The specified language can influence the set of results that the API chooses to return and the order in which they are returned. The geocoder interprets abbreviations differently depending on language, such as the abbreviations for street types, or synonyms that may be valid in one language but not in another. For example, utca and tér are synonyms for street in Hungarian.

Understand the geocodingResults array

For every location in the request (origin, destination, or intermediate waypoint) that was specified as an address string or as a Plus code, the API attempts to find the most relevant location which has a corresponding place ID. Each element of the geocodingResults array contains the placeID field containing the location as a place ID and a type field specifying the location type, such as street_address, premise, or airport.

Note: The API does not include locations in the request specified as a place ID or as latitude and longitude coordinates. If they are all in these formats, this array is not provided.

The geocodingResults array contains three fields:

• origin: If it was specified as an address string or as a Plus code, the place ID of the origin. Otherwise, this field is omitted from the response.

• destination: If it was specified as an address string or as a Plus code, the place ID of the destination. Otherwise, this field is omitted from the response.

• intermediates: An array containing the place ID of any intermediate waypoints specified as an address string or as a Plus code. If you specify an intermediate waypoint using a place ID or latitude and longitude coordinates, it is omitted from the response. Use the intermediateWaypointRequestIndex property in the response to determine which intermediate waypoint in the request corresponds to the place ID in the response.

Note: If a requested location does not exist or cannot be found, the API still populates the geocodingResults array in the response. However, the routes array is empty because no route can be computed for a location that cannot be found.

"geocodingResults": {
    "origin": {
        "geocoderStatus": {},
        "type": [
             enum (Type)
        ],
        "placeId": string
    },
    "destination": {
        "geocoderStatus": {},
        "type": [
            enum (Type)
        ],
        "placeId": string
    },
    "intermediates": [
        {
            "geocoderStatus": {},
            "intermediateWaypointRequestIndex": integer,
            "type": [
                enum (Type)
            ],
            "placeId": string
        },
        {
           "geocoderStatus": {},
           "intermediateWaypointRequestIndex": integer,
            "type": [
                enum (Type)
            ],
            "placeId": string
        }
    ]
}

Understand localized response values

Localized response values are an additional response field that provides localized text for returned parameter values. Localized text is provided for trip duration, distance, and unit system (metric or imperial). You request localized values using a field mask, and can either specify the language and unit system or use the values inferred by the API. For details, see LocalizedValues.

For example, if you specify a language code for German (de) and imperial units, you get a value for distanceMeters of 49889.7, but also localized text providing that distance measurement in German and imperial units, so "31 Meile."

Here is an example of what you would see for localized values:

{ "localized_values":
  {
    "distance": { "text": "31,0 Meile/n" },
    "duration": { "text": 38 Minuten}.
    "static_duration": { "text": 36 Minuten}.
  }
}

Note: You get two values for the expected duration: duration uses the traffic model you specify, and static_duration does not take traffic into account. So, if your requested traffic model is TRAFFIC_UNAWARE these times are identical.

If you don't specify the language or unit system, the API infers the language and units as follows:

• The ComputeRoutes method infers the location and distance units from the origin waypoint. So for a routing request in the US, the API infers en-US language and IMPERIAL units.
• The ComputeRouteMatrix method defaults to 'en-US' language and METRIC units.