Overview of search along route

Search along route features are available in the following Places (New) APIs:

• Text Search (New) only: Search for places along a predefined trip route.
• Text Search (New) and Nearby Search (New): Calculate the routing summary from a specified routing origin location to each place in the search results.
• Text Search (New) only: Calculate the routing summary for each place along a predefined trip route.

Search along a route

You use theRoutes API to calculate the trip routebetween two locations. The Routes API can calculate a route for a car, bicycle,two-wheel vehicle, transit system, or for walking.

Note: Transit system routes are not supported by the Places API.

Text Search (New) lets you use this calculated route to perform asearch along a route. With this option, you pass the precalculated routefrom the Routes API to the Text Search (New) request. The response then containsplaces that match the search criteria and are also located near the specifiedroute.

Searching along a route is similar to using thelocationRestriction orlocationBias request options to bias the search results.locationRestrictionreturns search results that fall within the viewport bounds, whilelocationBias may return search results outside of the viewport. However, whilethelocationBias andlocationRestriction options let you specify a region tobias the search results, the search along route feature in Text Search also letsyou bias the search results to include those with minimal detour times from theroute origin to the route destination. You can bias search results using eitherlocationBias orlocationRestriction in combination with the polyline.

For example, consider the route from the origin, referred to as awaypoint in the Routes API, to the destination as calculated by the RoutesAPI:

When you search along the route, the search is biased to return places near theroute with minimal detour times from the origin to the destination. In thisexample, points A, B, and C are places returned by the search.

Calculate routing summary

Text Search (New) andNearby Search (New) cancalculate therouting summary, meaning the duration and distance, to eachplace in the response based on the specifiedrouting origin location in therequest. When you specify the routing origin, the response not only contains alist of places that match the search, but also the travel duration and distancefrom the routing origin to each place.

In the following image, points A, B, and C are places returned in the searchresponse:

For each place in the results, the response contains the travel duration anddistance from the routing origin to the place, if available.

Note: This is only an estimate of the routing information. To get the actualroute details, including step-by-step directions, use theRoutesAPI.

By default, the travel duration and distance is calculated using theTRAFFIC_UNAWAREoption in the Routes API. You can optionally set routing preferences to takelive traffic conditionsTRAFFIC_AWARE_OPTIMALor latency-reduced live traffic conditionsTRAFFIC_AWAREinto consideration during calculations.

Note:TRAFFIC_AWARE andTRAFFIC_OPTIMAL only apply totheDRIVE andTWO_WHEELER travel modes. If either routing preference isspecified with an unsupported travel mode, the routing summary calculation defaults to using theTRAFFIC_UNAWARE option. IfTWO_WHEELER is specified in anunsupported region, the API returns anempty routing summary.When you set theTRAFFIC_AWARErouting preference, routes are calculated accounting for traffic conditions. Asa result, the route and route details more accurately reflect real-worldconditions. Since this increase in data quality comes at the expense of responselatency, performance optimizations are applied to reduce much of the latency. When you set theTRAFFIC_AWARE_OPTIMALrouting preference, routes are calculated accounting for traffic conditions, butno performance optimizations are applied. In this mode, the server performs amore exhaustive search of the road network to find the optimal route.

About routes, legs, and waypoints

Several components make up a route, as calculated by the Routes API:

A route consists of the following components:

• Waypoint: To calculate a route, you specify at a minimum the locations of the origin and destination. You define these locations aswaypoints on the route.Intermediate waypoints are locations in between the origin and destination that you want the route to go through.

• Route: The entire trip from the origin waypoint, through any intermediate waypoints, to the destination waypoint. A route consists of one or morelegs.

  When passing a route to Text Search, you pass theroute's encoded polyline as returned by theRoutes API. An encoded polyline is an encoded list of latitude and longitude points that lets you represent the route's polyline as a string.

• Leg: The path from one waypoint in a route to the next waypoint in the route. Each leg consists of one or more discretesteps.

  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 anintermediate waypoint, the API adds a separate leg.

For more information on routes and calculating routes, see theRoutesAPI.

Calculate the routing summary with a search along route

You can combinerouting summary calculations withsearch along a route.In this case,Text Search (New) returns the travel duration anddistance to each place in the response, and then from each place to the finaldestination of the route. Think of this calculation as providing a travelduration and distance if you detour from the specified route to travel to aplace in the search results, and then continue on to the final destination.

For example, consider the following route from the origin to the destination ascalculated by the Routes API. Pass this route to the Text Search (New) API alongwith your search criteria.

In this example, location A is a place returned in the search results from Text Search (New). For each place in the response, the search includes the durationand distance required to detour to that place as atwo-leg trip:

• The first leg contains the travel duration and distance from the routeorigin to theplace. In this example, from the origin to place A.
• The second leg contains the travel duration and distance from theplace to the routedestination. In this example, from A to the destination.

From the information in the response, you can then calculate thedetour duration and distance, where:

• \(t_{OD}\) is thetrip duration from the origin to the destination, \(s_{OD}\) is thetrip distance from the origin to the destination
• \(t_{OA}\) is thetrip duration from the origin to A; \(s_{OA}\) is thetrip distance from the origin to A
• \(t_{AD}\) is thetrip duration from A to the destination; \(s_{AD}\) is thetrip distance from A to the destination

Detour duration is theduration difference between theoriginal trip(from the origin to the destination) and thenew trip (from the origin tothe destinationthrough A):

Detour distance is thedistance difference between theoriginal trip(from the origin to the destination) and thenew trip (from the origin tothe destinationthrough A):