- HTTP request
- Request body
- Response body
- PolylineQuality
- PolylineEncoding
- ReferenceRoute
- ExtraComputation
- Route
- RouteLabel
- RouteLeg
- Polyline
- RouteLegStep
- NavigationInstruction
- Maneuver
- RouteLegStepTravelAdvisory
- RouteLegStepLocalizedValues
- RouteLegStepTransitDetails
- TransitStopDetails
- TransitStop
- TransitDetailsLocalizedValues
- LocalizedTime
- TransitLine
- TransitAgency
- TransitVehicle
- TransitVehicleType
- RouteLegTravelAdvisory
- RouteLegLocalizedValues
- StepsOverview
- MultiModalSegment
- Viewport
- RouteLocalizedValues
- GeocodingResults
- GeocodedWaypoint
Returns the primary route along with optional alternate routes, given a set of terminal and intermediate waypoints.
NOTE: This method requires that you specify a response field mask in the input. You can provide the response field mask by using URL parameter $fields
or fields
, or by using an HTTP/gRPC header X-Goog-FieldMask
(see the available URL parameters and headers). The value is a comma separated list of field paths. See detailed documentation about how to construct the field paths.
For example, in this method:
- Field mask of all available fields (for manual inspection):
X-Goog-FieldMask: *
- Field mask of Route-level duration, distance, and polyline (an example production setup):
X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline.encodedPolyline
Google discourage the use of the wildcard (*
) response field mask, or specifying the field mask at the top level (routes
), because:
- Selecting only the fields that you need helps our server save computation cycles, allowing us to return the result to you with a lower latency.
- Selecting only the fields that you need in your production job ensures stable latency performance. We might add more response fields in the future, and those new fields might require extra computation time. If you select all fields, or if you select all fields at the top level, then you might experience performance degradation because any new field we add will be automatically included in the response.
- Selecting only the fields that you need results in a smaller response size, and thus higher network throughput.
HTTP request
POST https://routes.googleapis.com/directions/v2:computeRoutes
The URL uses gRPC Transcoding syntax.
Request body
The request body contains data with the following structure:
JSON representation |
---|
{ "origin": { object ( |
Fields | |
---|---|
origin |
Required. Origin waypoint. |
destination |
Required. Destination waypoint. |
intermediates[] |
Optional. A set of waypoints along the route (excluding terminal points), for either stopping at or passing by. Up to 25 intermediate waypoints are supported. |
travelMode |
Optional. Specifies the mode of transportation. |
routingPreference |
Optional. Specifies how to compute the route. The server attempts to use the selected routing preference to compute the route. If the routing preference results in an error or an extra long latency, then an error is returned. You can specify this option only when the |
polylineQuality |
Optional. Specifies your preference for the quality of the polyline. |
polylineEncoding |
Optional. Specifies the preferred encoding for the polyline. |
departureTime |
Optional. The departure time. If you don't set this value, then this value defaults to the time that you made the request. NOTE: You can only specify a A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: |
arrivalTime |
Optional. The arrival time. NOTE: Can only be set when A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: |
computeAlternativeRoutes |
Optional. Specifies whether to calculate alternate routes in addition to the route. No alternative routes are returned for requests that have intermediate waypoints. |
routeModifiers |
Optional. A set of conditions to satisfy that affect the way routes are calculated. |
languageCode |
Optional. The BCP-47 language code, such as "en-US" or "sr-Latn". For more information, see Unicode Locale Identifier. See Language Support for the list of supported languages. When you don't provide this value, the display language is inferred from the location of the route request. |
regionCode |
Optional. The region code, specified as a ccTLD ("top-level domain") two-character value. For more information see Country code top-level domains. |
units |
Optional. Specifies the units of measure for the display fields. These fields include the |
optimizeWaypointOrder |
Optional. If set to true, the service attempts to minimize the overall cost of the route by re-ordering the specified intermediate waypoints. The request fails if any of the intermediate waypoints is a |
requestedReferenceRoutes[] |
Optional. Specifies what reference routes to calculate as part of the request in addition to the default route. A reference route is a route with a different route calculation objective than the default route. For example a |
extraComputations[] |
Optional. A list of extra computations which may be used to complete the request. Note: These extra computations may return extra fields on the response. These extra fields must also be specified in the field mask to be returned in the response. |
trafficModel |
Optional. Specifies the assumptions to use when calculating time in traffic. This setting affects the value returned in the duration field in the |
transitPreferences |
Optional. Specifies preferences that influence the route returned for |
Response body
v2.computeRoutes the response message.
If successful, the response body contains data with the following structure:
JSON representation |
---|
{ "routes": [ { object ( |
Fields | |
---|---|
routes[] |
Contains an array of computed routes (up to three) when you specify |
fallbackInfo |
In some cases when the server is not able to compute the route results with all of the input preferences, it may 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. |
geocodingResults |
Contains geocoding response info for waypoints specified as addresses. |
PolylineQuality
A set of values that specify the quality of the polyline.
Enums | |
---|---|
POLYLINE_QUALITY_UNSPECIFIED |
No polyline quality preference specified. Defaults to OVERVIEW . |
HIGH_QUALITY |
Specifies a high-quality polyline - which is composed using more points than OVERVIEW , at the cost of increased response size. Use this value when you need more precision. |
OVERVIEW |
Specifies an overview polyline - which is composed using a small number of points. Use this value when displaying an overview of the route. Using this option has a lower request latency compared to using the HIGH_QUALITY option. |
PolylineEncoding
Specifies the preferred type of polyline to be returned.
Enums | |
---|---|
POLYLINE_ENCODING_UNSPECIFIED |
No polyline type preference specified. Defaults to ENCODED_POLYLINE . |
ENCODED_POLYLINE |
Specifies a polyline encoded using the polyline encoding algorithm. |
GEO_JSON_LINESTRING |
Specifies a polyline using the GeoJSON LineString format |
ReferenceRoute
A supported reference route on the ComputeRoutesRequest.
Enums | |
---|---|
REFERENCE_ROUTE_UNSPECIFIED |
Not used. Requests containing this value fail. |
FUEL_EFFICIENT |
Fuel efficient route. Routes labeled with this value are determined to be optimized for parameters such as fuel consumption. |
ExtraComputation
Extra computations to perform while completing the request.
Enums | |
---|---|
EXTRA_COMPUTATION_UNSPECIFIED |
Not used. Requests containing this value will fail. |
TOLLS |
Toll information for the route(s). |
FUEL_CONSUMPTION |
Estimated fuel consumption for the route(s). |
TRAFFIC_ON_POLYLINE |
Traffic aware polylines for the route(s). |
HTML_FORMATTED_NAVIGATION_INSTRUCTIONS |
NavigationInstructions presented as a formatted HTML text string. This content is meant to be read as-is. This content is for display only. Do not programmatically parse it. |
Route
Contains a route, which consists of a series of connected road segments that join beginning, ending, and intermediate waypoints.
JSON representation |
---|
{ "routeLabels": [ enum ( |
Fields | |
---|---|
routeLabels[] |
Labels for the |
legs[] |
A collection of legs (path segments between waypoints) that make up the route. Each leg corresponds to the trip between two non- |
distanceMeters |
The travel distance of the route, in meters. |
duration |
The length of time needed to navigate the route. If you set the A duration in seconds with up to nine fractional digits, ending with ' |
staticDuration |
The duration of travel through the route without taking traffic conditions into consideration. A duration in seconds with up to nine fractional digits, ending with ' |
polyline |
The overall route polyline. This polyline is the combined polyline of all |
description |
A description of the route. |
warnings[] |
An array of warnings to show when displaying the route. |
viewport |
The viewport bounding box of the polyline. |
travelAdvisory |
Additional information about the route. |
optimizedIntermediateWaypointIndex[] |
If you set |
localizedValues |
Text representations of properties of the |
routeToken |
A web-safe, base64-encoded route token that can be passed to the Navigation SDK, that allows the Navigation SDK to reconstruct the route during navigation, and, in the event of rerouting, honor the original intention when you created the route by calling v2.computeRoutes. Customers should treat this token as an opaque blob. Do not compare its value across requests -- this token may change even if the exact same route was returned. NOTE: |
RouteLabel
Labels for the
that are useful to identify specific properties of the route to compare against others.Route
Enums | |
---|---|
ROUTE_LABEL_UNSPECIFIED |
Default - not used. |
DEFAULT_ROUTE |
The default "best" route returned for the route computation. |
DEFAULT_ROUTE_ALTERNATE |
An alternative to the default "best" route. Routes like this will be returned when is specified. |
FUEL_EFFICIENT |
Fuel efficient route. Routes labeled with this value are determined to be optimized for Eco parameters such as fuel consumption. |
RouteLeg
Contains a segment between non-via
waypoints.
JSON representation |
---|
{ "distanceMeters": integer, "duration": string, "staticDuration": string, "polyline": { object ( |
Fields | |
---|---|
distanceMeters |
The travel distance of the route leg, in meters. |
duration |
The length of time needed to navigate the leg. If the A duration in seconds with up to nine fractional digits, ending with ' |
staticDuration |
The duration of travel through the leg, calculated without taking traffic conditions into consideration. A duration in seconds with up to nine fractional digits, ending with ' |
polyline |
The overall polyline for this leg that includes each |
startLocation |
The start location of this leg. This location might be different from the provided |
endLocation |
The end location of this leg. This location might be different from the provided |
steps[] |
An array of steps denoting segments within this leg. Each step represents one navigation instruction. |
travelAdvisory |
Contains the additional information that the user should be informed about, such as possible traffic zone restrictions, on a route leg. |
localizedValues |
Text representations of properties of the |
stepsOverview |
Overview information about the steps in this |
Polyline
Encapsulates an encoded polyline.
JSON representation |
---|
{ // Union field |
Fields | |
---|---|
Union field polyline_type . Encapsulates the type of polyline. Defaults to encoded_polyline. polyline_type can be only one of the following: |
|
encodedPolyline |
The string encoding of the polyline using the polyline encoding algorithm |
geoJsonLinestring |
Specifies a polyline using the GeoJSON LineString format. |
RouteLegStep
Contains a segment of a
. A step corresponds to a single navigation instruction. Route legs are made up of steps.RouteLeg
JSON representation |
---|
{ "distanceMeters": integer, "staticDuration": string, "polyline": { object ( |
Fields | |
---|---|
distanceMeters |
The travel distance of this step, in meters. In some circumstances, this field might not have a value. |
staticDuration |
The duration of travel through this step without taking traffic conditions into consideration. In some circumstances, this field might not have a value. A duration in seconds with up to nine fractional digits, ending with ' |
polyline |
The polyline associated with this step. |
startLocation |
The start location of this step. |
endLocation |
The end location of this step. |
navigationInstruction |
Navigation instructions. |
travelAdvisory |
Contains the additional information that the user should be informed about, such as possible traffic zone restrictions, on a leg step. |
localizedValues |
Text representations of properties of the |
transitDetails |
Details pertaining to this step if the travel mode is |
travelMode |
The travel mode used for this step. |
Maneuver
A set of values that specify the navigation action to take for the current step (for example, turn left, merge, or straight).
Enums | |
---|---|
MANEUVER_UNSPECIFIED |
Not used. |
TURN_SLIGHT_LEFT |
Turn slightly to the left. |
TURN_SHARP_LEFT |
Turn sharply to the left. |
UTURN_LEFT |
Make a left u-turn. |
TURN_LEFT |
Turn left. |
TURN_SLIGHT_RIGHT |
Turn slightly to the right. |
TURN_SHARP_RIGHT |
Turn sharply to the right. |
UTURN_RIGHT |
Make a right u-turn. |
TURN_RIGHT |
Turn right. |
STRAIGHT |
Go straight. |
RAMP_LEFT |
Take the left ramp. |
RAMP_RIGHT |
Take the right ramp. |
MERGE |
Merge into traffic. |
FORK_LEFT |
Take the left fork. |
FORK_RIGHT |
Take the right fork. |
FERRY |
Take the ferry. |
FERRY_TRAIN |
Take the train leading onto the ferry. |
ROUNDABOUT_LEFT |
Turn left at the roundabout. |
ROUNDABOUT_RIGHT |
Turn right at the roundabout. |
DEPART |
Initial maneuver. |
NAME_CHANGE |
Used to indicate a street name change. |
RouteLegStepTravelAdvisory
Contains the additional information that the user should be informed about, such as possible traffic zone restrictions on a leg step.
JSON representation |
---|
{
"speedReadingIntervals": [
{
object ( |
Fields | |
---|---|
speedReadingIntervals[] |
NOTE: This field is not currently populated. |
RouteLegStepLocalizedValues
Text representations of certain properties.
JSON representation |
---|
{ "distance": { object ( |
Fields | |
---|---|
distance |
Travel distance represented in text form. |
staticDuration |
Duration without taking traffic conditions into consideration, represented in text form. |
RouteLegStepTransitDetails
Additional information for the RouteLegStep
related to TRANSIT
routes.
JSON representation |
---|
{ "stopDetails": { object ( |
Fields | |
---|---|
stopDetails |
Information about the arrival and departure stops for the step. |
localizedValues |
Text representations of properties of the |
headsign |
Specifies the direction in which to travel on this line as marked on the vehicle or at the departure stop. The direction is often the terminus station. |
headway |
Specifies the expected time as a duration between departures from the same stop at this time. For example, with a headway seconds value of 600, you would expect a ten minute wait if you should miss your bus. A duration in seconds with up to nine fractional digits, ending with ' |
transitLine |
Information about the transit line used in this step. |
stopCount |
The number of stops from the departure to the arrival stop. This count includes the arrival stop, but excludes the departure stop. For example, if your route leaves from Stop A, passes through stops B and C, and arrives at stop D, stopCount will return 3. |
tripShortText |
The text that appears in schedules and sign boards to identify a transit trip to passengers. The text should uniquely identify a trip within a service day. For example, "538" is the |
TransitStopDetails
Details about the transit stops for the RouteLegStep
.
JSON representation |
---|
{ "arrivalStop": { object ( |
Fields | |
---|---|
arrivalStop |
Information about the arrival stop for the step. |
arrivalTime |
The estimated time of arrival for the step. A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: |
departureStop |
Information about the departure stop for the step. |
departureTime |
The estimated time of departure for the step. A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: |
TransitStop
Information about a transit stop.
JSON representation |
---|
{
"name": string,
"location": {
object ( |
Fields | |
---|---|
name |
The name of the transit stop. |
location |
The location of the stop expressed in latitude/longitude coordinates. |
TransitDetailsLocalizedValues
Localized descriptions of values for RouteTransitDetails
.
JSON representation |
---|
{ "arrivalTime": { object ( |
Fields | |
---|---|
arrivalTime |
Time in its formatted text representation with a corresponding time zone. |
departureTime |
Time in its formatted text representation with a corresponding time zone. |
LocalizedTime
Localized description of time.
JSON representation |
---|
{
"time": {
object ( |
Fields | |
---|---|
time |
The time specified as a string in a given time zone. |
timeZone |
Contains the time zone. The value is the name of the time zone as defined in the IANA Time Zone Database, e.g. "America/New_York". |
TransitLine
Contains information about the transit line used in this step.
JSON representation |
---|
{ "agencies": [ { object ( |
Fields | |
---|---|
agencies[] |
The transit agency (or agencies) that operates this transit line. |
name |
The full name of this transit line, For example, "8 Avenue Local". |
uri |
the URI for this transit line as provided by the transit agency. |
color |
The color commonly used in signage for this line. Represented in hexadecimal. |
iconUri |
The URI for the icon associated with this line. |
nameShort |
The short name of this transit line. This name will normally be a line number, such as "M7" or "355". |
textColor |
The color commonly used in text on signage for this line. Represented in hexadecimal. |
vehicle |
The type of vehicle that operates on this transit line. |
TransitAgency
A transit agency that operates a transit line.
JSON representation |
---|
{ "name": string, "phoneNumber": string, "uri": string } |
Fields | |
---|---|
name |
The name of this transit agency. |
phoneNumber |
The transit agency's locale-specific formatted phone number. |
uri |
The transit agency's URI. |
TransitVehicle
Information about a vehicle used in transit routes.
JSON representation |
---|
{ "name": { object ( |
Fields | |
---|---|
name |
The name of this vehicle, capitalized. |
type |
The type of vehicle used. |
iconUri |
The URI for an icon associated with this vehicle type. |
localIconUri |
The URI for the icon associated with this vehicle type, based on the local transport signage. |
TransitVehicleType
The type of vehicles for transit routes.
Enums | |
---|---|
TRANSIT_VEHICLE_TYPE_UNSPECIFIED |
Unused. |
BUS |
Bus. |
CABLE_CAR |
A vehicle that operates on a cable, usually on the ground. Aerial cable cars may be of the type GONDOLA_LIFT . |
COMMUTER_TRAIN |
Commuter rail. |
FERRY |
Ferry. |
FUNICULAR |
A vehicle that is pulled up a steep incline by a cable. A Funicular typically consists of two cars, with each car acting as a counterweight for the other. |
GONDOLA_LIFT |
An aerial cable car. |
HEAVY_RAIL |
Heavy rail. |
HIGH_SPEED_TRAIN |
High speed train. |
INTERCITY_BUS |
Intercity bus. |
LONG_DISTANCE_TRAIN |
Long distance train. |
METRO_RAIL |
Light rail transit. |
MONORAIL |
Monorail. |
OTHER |
All other vehicles. |
RAIL |
Rail. |
SHARE_TAXI |
Share taxi is a kind of bus with the ability to drop off and pick up passengers anywhere on its route. |
SUBWAY |
Underground light rail. |
TRAM |
Above ground light rail. |
TROLLEYBUS |
Trolleybus. |
RouteLegTravelAdvisory
Contains the additional information that the user should be informed about on a leg step, such as possible traffic zone restrictions.
JSON representation |
---|
{ "tollInfo": { object ( |
Fields | |
---|---|
tollInfo |
Contains information about tolls on the specific |
speedReadingIntervals[] |
Speed reading intervals detailing traffic density. Applicable in case of Example:
|
RouteLegLocalizedValues
Text representations of certain properties.
JSON representation |
---|
{ "distance": { object ( |
Fields | |
---|---|
distance |
Travel distance represented in text form. |
duration |
Duration taking traffic conditions into consideration represented in text form. Note: If you did not request traffic information, this value will be the same value as staticDuration. |
staticDuration |
Duration without taking traffic conditions into consideration, represented in text form. |
StepsOverview
Provides overview information about a list of RouteLegStep
s.
JSON representation |
---|
{
"multiModalSegments": [
{
object ( |
Fields | |
---|---|
multiModalSegments[] |
Summarized information about different multi-modal segments of the |
MultiModalSegment
Provides summarized information about different multi-modal segments of the RouteLeg.steps
. A multi-modal segment is defined as one or more contiguous RouteLegStep
that have the same RouteTravelMode
. This field is not populated if the RouteLeg
does not contain any multi-modal segments in the steps.
JSON representation |
---|
{ "navigationInstruction": { object ( |
Fields | |
---|---|
navigationInstruction |
NavigationInstruction for the multi-modal segment. |
travelMode |
The travel mode of the multi-modal segment. |
stepStartIndex |
The corresponding |
stepEndIndex |
The corresponding |
Viewport
A latitude-longitude viewport, represented as two diagonally opposite low
and high
points. A viewport is considered a closed region, i.e. it includes its boundary. The latitude bounds must range between -90 to 90 degrees inclusive, and the longitude bounds must range between -180 to 180 degrees inclusive. Various cases include:
If
low
=high
, the viewport consists of that single point.If
low.longitude
>high.longitude
, the longitude range is inverted (the viewport crosses the 180 degree longitude line).If
low.longitude
= -180 degrees andhigh.longitude
= 180 degrees, the viewport includes all longitudes.If
low.longitude
= 180 degrees andhigh.longitude
= -180 degrees, the longitude range is empty.If
low.latitude
>high.latitude
, the latitude range is empty.
Both low
and high
must be populated, and the represented box cannot be empty (as specified by the definitions above). An empty viewport will result in an error.
For example, this viewport fully encloses New York City:
{ "low": { "latitude": 40.477398, "longitude": -74.259087 }, "high": { "latitude": 40.91618, "longitude": -73.70018 } }
JSON representation |
---|
{ "low": { object ( |
Fields | |
---|---|
low |
Required. The low point of the viewport. |
high |
Required. The high point of the viewport. |
RouteLocalizedValues
Text representations of certain properties.
JSON representation |
---|
{ "distance": { object ( |
Fields | |
---|---|
distance |
Travel distance represented in text form. |
duration |
Duration taking traffic conditions into consideration, represented in text form. Note: If you did not request traffic information, this value will be the same value as |
staticDuration |
Duration without taking traffic conditions into consideration, represented in text form. |
transitFare |
Transit fare represented in text form. |
GeocodingResults
Contains
for origin, destination and intermediate waypoints. Only populated for address waypoints.GeocodedWaypoints
JSON representation |
---|
{ "origin": { object ( |
Fields | |
---|---|
origin |
Origin geocoded waypoint. |
destination |
Destination geocoded waypoint. |
intermediates[] |
A list of intermediate geocoded waypoints each containing an index field that corresponds to the zero-based position of the waypoint in the order they were specified in the request. |
GeocodedWaypoint
Details about the locations used as waypoints. Only populated for address waypoints. Includes details about the geocoding results for the purposes of determining what the address was geocoded to.
JSON representation |
---|
{
"geocoderStatus": {
object ( |
Fields | |
---|---|
geocoderStatus |
Indicates the status code resulting from the geocoding operation. |
type[] |
The type(s) of the result, in the form of zero or more type tags. Supported types: Address types and address component types. |
partialMatch |
Indicates that the geocoder did not return an exact match for the original request, though it was able to match part of the requested address. You may wish to examine the original request for misspellings and/or an incomplete address. |
placeId |
The place ID for this result. |
intermediateWaypointRequestIndex |
The index of the corresponding intermediate waypoint in the request. Only populated if the corresponding waypoint is an intermediate waypoint. |