Generate large vehicle routes & ETAs

Who this guide is for: Read this guide if you are a developer building services for trip planning and execution using trucks or other large vehicles. Relevant use cases include calculating travel times and distances, computing ETAs, or generating routes that will be used by a navigation application.

What this guide covers: This guide covers how to use the Routes API with Large Vehicle Routing to request routes, travel distance, predicted travel time, and ETAs that account for the specific attributes of a large vehicle, such as a commercial truck or a passenger bus.

For information on how to perform fleet-level computations for large vehicles using the Route Optimization API, see the Route Optimization Truck Routing Documentation.

What you'll learn

You'll learn how to do the following:

• Construct a valid routing request.
• Specify the vehicle information for your real-world vehicle, using dimensions, weight, and other characteristics.
• Interpret the response, including the route token and travel safety flags.

Prerequisites

1. Your Google Cloud project must be created and the Routes API must be enabled.
2. Your project must be provisioned for Large Vehicle Routing. Large vehicle routing is available to a limited set of customers, contact us to request access

Limitations

Before you begin, you must be aware of the following limitations and requirements.

• Geographic availability: Large vehicle routing is available only in the contiguous 48 United States.
• Driver advisory and safety. Drivers must not rely solely on routes returned by this API to be safe or legal. Routes are not guaranteed to be appropriate for the vehicle, and following them may expose drivers to hazards such as low bridges or roads where large vehicles are prohibited.
• Best-effort routes. In some cases, the API cannot find a route that fully complies with travel restrictions. Instead, it returns a "best effort" route that may still traverse restricted areas. The Routes API response clearly flags these routes in the routeRestrictionsPartiallyIgnored field. Plan your route carefully in these cases, ideally using other source data. Don't use a flagged route as a single source of truth for planning or navigation.
• Unsupported features: Large vehicle routing does not support the following:
  • Truck toll prices
  • Speed limits
  • Routing for radioactive hazardous materials
• Usage limits: All requests are subject to standard query-per-second (QPS) limits.

Build a truck route request

To get a truck route, you send an HTTPS request to a Routes API endpoint with specific parameters that describe your vehicle. The concepts in this section apply to both single route and route matrix requests.

Endpoints

You can use two endpoints for truck routing:

• computeRoutes: Calculates a single route between one origin and one destination.
• computeRouteMatrix: Calculates the distance and duration for a matrix of origins and destinations, but does not return a route polyline.

Key request parameters

In your request body, you must include the following parameters to enable truck routing:

• travelMode: Set this value to TRUCK.
• routingPreference: Set this value to TRAFFIC_AWARE_OPTIMAL.
• routeModifiers: This object contains the vehicleInfo object where you define your vehicle's attributes. The vehicleInfo object is described in detail below.

Specify vehicle attributes

In order to send a request, you must supply a request body with a vehicleInfo object that describes your vehicle. Think of this information as a specification that matches the physical details of your real-world vehicle. The service requires these details in order to return routes that take into account road restrictions based on your vehicle's attributes.

Vehicle measurements

Provide vehicle weight in kilograms and vehicle dimensions in millimeters, as indicated by the field names. For example, total height should be supplied in millimeters (totalHeightMm). Since truck dimensions are often expressed in feet or meters, this may require a unit conversion.

Conversion from imperial to metric

When converting from imperial units, always consider your specific vehicle dimensions alongside standard road and underpass size limits. This can be especially important with fractional values. Depending on the size of the actual vehicle, rounding up a fractional value can result in overly restrictive routing for the vehicle.

For example:

• Width: Many US trailers have a width of 8' 6", which converts to 2,590.8mm. Rounding up to 2,591mm would indicate the vehicle is greater than 8' 6", which would classify it as an oversize vehicle on US roads. This would then result in a route that was computed according to meaningfully different constraints than intended.
• Height: A route leading under an 11' bridge wouldn't be suitable for a typical tractor-trailer with a height of 13.5'. However, smaller box trucks around 10' would be able to navigate the underpass. Accordingly, it's critical to specify your vehicle attributes accurately.

Following is a code snippet that shows an example vehicleInfo object:

"vehicleInfo": {
      "totalAxleCount": 5,
      "totalHeightMm": 4114,
      "totalLengthMm": 21945,
      "totalWidthMm": 2590,
      "totalWeightKg": 32658,
      "trailerInfo": [{
        "lengthMm": 16154
      }

vehicleInfo object fields

The following table shows all vehicle and load definitions you can send with the request.

Use field masks

For best results, include the X-Goog-FieldMask header in your request to specify exactly those fields you want in the response. Field masks reduce latency and ensure you receive important advisory fields. At a minimum, always include routes.travelAdvisory.routeRestrictionsPartiallyIgnored in the field mask, since this indicates whether the route has one or more restrictions that apply to your vehicle.

For more details on FieldMasks with Routes API, see this article.

Tolls

To prefer toll-free routes, specify avoidTolls in the routeModifiers property of a request. For more information on route modifiers, see Specify route features to avoid.

Specifying avoidTolls does not guarantee toll-free routes in the response. In some cases, using a toll road is required to travel between the origin and destination. If you include routes.warnings in the fieldmask of your Routes API request, routes containing toll roads will be annotated accordingly within this field.

Other routing behaviors

When you set the travelMode to TRUCK, the API automatically optimizes the route for the maneuverability of large vehicles. Generated routes avoid U-turns and strongly prefer interstates and highways over smaller roads. You don't need to set any additional parameters or modifiers to enable these behaviors.

Calculate a single route with computeRoutes

Use the computeRoutes endpoint to calculate a truck-specific route between one origin and one destination.

Example computeRoutes request

Here is a complete curl request for a typical semi-trailer truck. This example includes the endpoint, headers, and the request body.

curl --location 'https://routes.googleapis.com/directions/v2:computeRoutes' \
--header 'Content-Type: application/json' \
--header 'X-Goog-Api-Key: YOUR_API_KEY' \
--header 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.routeToken,routes.travelAdvisory.routeRestrictionsPartiallyIgnored' \
--data '{
 "origin": {
    "location": {
      "latLng": {
        "latitude": 40.883274,
        "longitude": -74.704574
      }
    }
  },
  "destination": {
    "location": {
      "latLng": {
        "latitude": 40.991920,
        "longitude": -75.183371
      }
    }
  },
  "travelMode": "TRUCK",
  "routingPreference": "TRAFFIC_AWARE_OPTIMAL",
  "routeModifiers": {
    "vehicleInfo": {
      "totalAxleCount": 5,
      "totalHeightMm": 4114,
      "totalLengthMm": 21945,
      "totalWidthMm": 2590,
      "totalWeightKg": 32658,
      "trailerInfo": [{
        "lengthMm": 16154
      }]
    }
  }
}'

Example computeRoutes response

This is an example response for the previous request shown above. Note that in the travelAdvisory object, the routeRestrictionsPartiallyIgnored flag is not included. This indicates that the route is not flagged and is believed to be fully compliant with the vehicle's attributes.

{
  "routes": [
    {
      "distanceMeters": 3426,
      "duration": "312s",
      "travelAdvisory": {},
      "routeToken": "CogCCogBChA7b39q54cKGCys_VXaDADjEhgszp8YhZFw0xvzm7SygpvCeIvJ7V0r6XIaJZ6BxNkMa_8HhhqlAci7hYMXi6UCpPgDW-yoAf8gzgHiEYyJAnoiAQU6AQFCB27cD9UCwwdKCMX2Ij7RpxY_eAGqARdUNENZWllLS0tJRGZ2T01QMVptSjRBaxAEGmIKYBIWCAAQAxAGEBMQEhgCQgQaAggFSgIIASIbChdUNENZWmVTc0o0RGZ2T01QMVptSjRBa3ABKAQyJ3RydWNraW5nOjpzZW1pLXRyYWlsZXItdHJ1Y2staGVhdnktc29mdCIVAOzExFsGGGfjVIIY7GXjYbPyONS8EiQiInRydWNraW5nOjpzZW1pLXRyYWlsZXItdHJ1Y2staGVhdnk"
    }
  ]
}

Interpret the computeRoutes response

A successful request to the computeRoutes endpoint returns a JSON response object containing one or more possible routes.

Key response fields

• Encoded route geometry: routes.polyline. This can be used to render the route on a map.
• Estimated trip duration: routes.duration (in seconds). Large vehicle routing trip duration uses a new model trained on observed travel speeds of actual trucks on the road network. It can also be used to compute ETA by adding the estimated trip duration to the expected departure time.
• Total distance of the route: routes.distanceMeters (in meters).
• Route token: routes.routeToken. This is an opaque token that represents the exact calculated route. You pass this token to the Navigation SDK to ensure the driver is shown the same truck-specific route. For more details on how to do that, review the Provide turn-by-turn navigation guide.

Check for route safety flags

When you get a response, the first thing you should do is check for route safety flags. If a provided route contains one or more restrictions making it unsuitable for the vehicle, you will find the travelAdvisory.routeRestrictionsPartiallyIgnored field set to true.

This field acts as a flag to answer the question, "Is this route flagged for a potential issue?"

• false(or omitted from response): The route is not flagged. The system found a route that is believed to be fully compliant with the parameters you supplied in the request.
• true: The route is flagged. The system could not find a fully compliant route and has returned a "best effort" route that may not be safe or legal. This route must be used with extreme caution.

Calculate a matrix of routes (computeRouteMatrix)

Use the computeRouteMatrix endpoint to efficiently compare travel times and distances between many origins and destinations. For example, you might use it to find the closest truck to a new pickup location. Once you identify the vehicle origin you want to use for your purpose, you may issue a computeRoutes request in order to get the route details and the route token for the proposed vehicle.

To use computeRouteMatrix, you specify the vehicleInfo within each origin object rather than at the root of the request.

Example computeRouteMatrix request

{
  "origins": [
    {
      "waypoint": { "location": { "latLng": { "latitude": 32.77, "longitude": -96.85 }}},
      "routeModifiers": { "vehicleInfo": { /* ...vehicle attributes... */ } }
    },
    {
      "waypoint": { "location": { "latLng": { "latitude": 33.61, "longitude": -112.11 }}},
      "routeModifiers": { "vehicleInfo": { /* ...vehicle attributes... */ } }
    }
  ],
  "destinations": [
    { "waypoint": { "location": { "latLng": { "latitude": 35.02, "longitude": -106.64 }}}},
    { "waypoint": { "location": { "latLng": { "latitude": 29.77, "longitude": -95.40 }}}}
  ],
  "travelMode": "TRUCK",
  "routingPreference": "TRAFFIC_AWARE_OPTIMAL"
}

Example computeRouteMatrix response

The response is an array where each object contains the duration and distanceMeters for one origin-destination pair.

[
  {
    "originIndex": 0,
    "destinationIndex": 1,
    "status": {},
    "distanceMeters": 392372,
    "duration": "14037s",
    "condition": "ROUTE_EXISTS"
  },
  { ... }
]

Next steps

• Provide Turn-by-Turn Directions: Learn how to use the routeToken in Provide turn-by-turn navigation with truck-specific routes.
• Perform Fleet-Level Optimization: Use Route Optimization API with Large Vehicle Routing.
• API Reference: For a complete list of all possible fields and values, see the Routes API Reference.