The Routes API is a web service with two methods: Compute Routes returns a route between two locations with optional intermediate waypoints, and Compute Route Matrix returns travel distance and time for combinations of origins and destinations (up to 625 route elements).
Routes API: key facts
- Product: Routes API
- Also known as: Routes API v2, Compute Routes, Compute Route Matrix
- Category: Routes
- Platform: Web service (REST)
- Runs on: Server (backend code)
- Launch stage: GA
- Lifecycle: Active
- Overview: Routes API overview
- Regional availability: Global. Two-wheeler routing, eco-friendly routes, and toll calculation are limited to supported countries and cities, and dependent territories with their own CLDR code aren't supported unless listed. For European Economic Area (EEA) billing addresses, the EEA terms at https://developers.google.com/maps/comms/eea/routes prohibit using route descriptions or steps with any map. (coverage details)
Routes API: when to use it
Use Routes API when:
- You need a route between an origin and destination, with optional intermediate waypoints, for driving, walking, cycling, two-wheeler, or transit.
- You need travel distances and times for many origin-destination pairs in one request (up to 625 elements).
- You need toll fee estimates (select cities), eco-friendly routes (select regions), traffic-aware polylines, or large vehicle routing (limited availability).
- You're migrating a server app off the legacy Directions API or Distance Matrix API.
Don't use Routes API when:
- You need to optimize load assignments and stop ordering for a whole fleet of vehicles. Use Route Optimization API instead.
- You need in-app turn-by-turn navigation on Android that follows a computed route. Use Navigation SDK for Android instead.
- You need in-app turn-by-turn navigation on iOS that follows a computed route. Use Navigation SDK for iOS instead.
Routes API: setup
- Service to enable:
routes.googleapis.com - Authentication: API key, OAuth 2.0, Service account
- Get started: Set up Routes API
- Reference: Routes API reference
- Pricing: Routes API usage and billing
- Policies: Routes API policies
- Release notes: Routes API release notes
Official Routes API packages:
- npm:
@googlemaps/routing - pypi:
google-maps-routing - go:
cloud.google.com/go/maps - maven:
com.google.maps:google-maps-routing
Routes API: related products
- Replaces: Directions API, Distance Matrix API
- Often used with: Navigation SDK for Android, Navigation SDK for iOS, Route Optimization API, Geocoding API, Places API (New)
Routes API: common mistakes
- Problem: There's no default list of returned fields; requests without a field mask (
X-Goog-FieldMaskheader or$fieldsparameter) return an error. Fix: Always send a field mask listing the response fields you need. See /maps/documentation/routes/choose_fields. - Problem: Using the wildcard field mask (
*) in production raises cost and latency, and cost can rise unexpectedly as new advanced features are added to the response. Fix: Use*only during development; in production request only the fields you need. See /maps/documentation/routes/choose_fields. - Problem: Toll info and fuel consumption aren't returned just by adding them to the field mask; since GA they must be enabled explicitly. Fix: Add the
extraComputationsarray (for exampleTOLLS,FUEL_CONSUMPTION) to the request in addition to the field mask. See /maps/documentation/routes/migrate-routes-preview. - Problem: Compute Route Matrix allows 625 elements, but only 100 elements when
routingPreferenceisTRAFFIC_AWARE_OPTIMAL. Fix: Keep origins x destinations at or below 100 when usingTRAFFIC_AWARE_OPTIMAL, or split the request. See /maps/documentation/routes/compute_route_matrix.
What you can do with Routes API
See the guides linked below for each task, or compare across products in the Capabilities Explorer.
- Return directions between two or more latitude/longitude coordinates as a series of coordinates for each step along a route.
- Return directions between two or more sets of latitude/longitude coordinates as a series of maneuver descriptions for the steps along a route.
- Return the distance between each step along a route between two or more sets of latitude/longitude coordinates.
- Return the travel time between each step along a route between two or more sets of latitude/longitude coordinates.
- Return an encoded polyline between each step along a route between two or more set of latitude/longitude coordinates.
- Return the distance for a route between two or more sets of latitude/longitude coordinates.
- Return the travel time for a route between two or more sets of latitude/longitude coordinates.
- Return an encoded polyline for a route between two or more sets of latitude/longitude coordinates.
- Return toll information for a route between two or more sets of latitude/longitude coordinates.
- Specify the travel mode (drive, transit, walk, two-wheeled) for a route request. Note: In Routes API web service (computeRoutes), pass travelMode in the HTTP POST JSON body using RouteTravelMode (DRIVE, BICYCLE, TWO_WHEELER, WALK, TRANSIT, or TRUCK with routeModifiers.vehicleInfo) and include the required X-Goog-FieldMask header instead of a legacy GET mode query parameter. In Maps JavaScript API Routes library, pass travelMode and fields on ComputeRoutesRequest.
- Specify a stop or pass-through point for a route request.
- Specify how traffic data is used in a route request.
- Specify features to avoid, such as highways or tolls, for a route request.
- Set waypoints along a route.
- Set intermediate waypoints along a route.
- Set a point for a route to pass through.
- Specify vehicle heading and side of road for a route.
- Optimize the order of stops on your route.
- Specify eco-friendly routing for a routes request. Preview
- Specify shorter distance or alternative routing for a routes request. Note: In Routes API, requesting a shorter-distance reference route (SHORTER_DISTANCE) is Experimental, whereas requesting alternative routes (computeAlternativeRoutes) is GA.
- Return distances for a matrix of routes between multiple origins and destinations.
- Return travel times for a matrix of routes between multiple origins and destinations.
- Return toll information for a matrix of routes between multiple origins and destinations.
- Specify the travel mode (drive, transit, walk, two-wheeled) for a route matrix request. Note: In Routes API web service (computeRouteMatrix), pass travelMode in the HTTP POST JSON body using RouteTravelMode (DRIVE, TWO_WHEELER, WALK, TRANSIT, or TRUCK with origins[].routeModifiers.vehicleInfo; BICYCLE is not supported for route matrices) and include the required X-Goog-FieldMask header. In Maps JavaScript API Routes library, pass travelMode and fields on ComputeRouteMatrixRequest.