# 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 the [Routes API](https://developers.google.com/maps/documentation/routes) to calculate the trip route
between two locations. The Routes API can calculate a route for a car, bicycle,
two-wheel vehicle, transit system, or for walking.

> [!NOTE]
> **Note:** Transit system routes aren't supported by the Places API (New).

[Text Search (New)](https://developers.google.com/maps/documentation/places/ios-sdk/text-search.md.txt) lets you use this calculated route to perform a
**search along a route**. With this option, you pass the precalculated route
from the Routes API to the Text Search (New) request. The response then contains
places that match the search criteria and are also located near the specified
route.

Searching along a route is similar to using the `locationRestriction` or
`locationBias` request options to bias the search results. `locationRestriction`
returns search results that fall within the viewport bounds, while
`locationBias` may return search results outside of the viewport. However, while
the `locationBias` and `locationRestriction` options let you specify a region to
bias the search results, the search along route feature in Text Search also lets
you bias the search results to include those with minimal detour times from the
route origin to the route destination. You can bias search results using either
`locationBias` or `locationRestriction` in combination with the polyline.

For example, consider the route from the origin, referred to as a
**waypoint** in the Routes API, to the destination as calculated by the Routes
API:
![Route from the origin waypoint to the destination with search results.](https://developers.google.com/static/maps/documentation/places/images/searchAlongRoute.svg)

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

## Calculate routing summary

[Text Search (New)](https://developers.google.com/maps/documentation/places/ios-sdk/text-search.md.txt) and [Nearby Search (New)](https://developers.google.com/maps/documentation/places/ios-sdk/nearby-search.md.txt) can
calculate the **routing summary** , meaning the duration and distance, to each
place in the response based on the specified **routing origin location** in the
request. When you specify the routing origin, the response not only contains a
list of places that match the search, but also the travel duration and distance
from the routing origin to each place.

In the following image, points A, B, and C are places returned in the search
response:
![Points A, B, and C are places returned in the search response.](https://developers.google.com/static/maps/documentation/places/images/calcTravelTime.svg)

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

> [!NOTE]
> **Note:** This is only an estimate of the routing information. To get the actual route details, including step-by-step directions, use the [Routes
> API](https://developers.google.com/maps/documentation/routes/compute_route_directions).

By default, the travel duration and distance is calculated using the [`TRAFFIC_UNAWARE`](https://developers.google.com/maps/documentation/routes/config_trade_offs.md.txt#traffic_unaware)
option in the Routes API. You can optionally set routing preferences to take
live traffic conditions [`TRAFFIC_AWARE_OPTIMAL`](https://developers.google.com/maps/documentation/routes/config_trade_offs.md.txt#traffic_aware_optimal)
or latency-reduced live traffic conditions [`TRAFFIC_AWARE`](https://developers.google.com/maps/documentation/routes/config_trade_offs.md.txt#traffic_aware)
into consideration during calculations.

> [!NOTE]
> **Note:** `TRAFFIC_AWARE` and `TRAFFIC_OPTIMAL` only apply to the `DRIVE` and `TWO_WHEELER` travel modes. If either routing preference is specified with an unsupported travel mode, the routing summary calculation defaults to using the `TRAFFIC_UNAWARE` option. If `TWO_WHEELER` is specified in an [unsupported region](https://developers.google.com/maps/documentation/routes/coverage-two-wheeled.md.txt), the API returns an empty routing summary.

> [!CAUTION]
> When you set the [`TRAFFIC_AWARE`](https://developers.google.com/maps/documentation/routes/config_trade_offs.md.txt#traffic_aware) routing preference, routes are calculated accounting for traffic conditions. As a result, the route and route details more accurately reflect real-world conditions. Since this increase in data quality comes at the expense of response latency, performance optimizations are applied to reduce much of the latency. When you set the [`TRAFFIC_AWARE_OPTIMAL`](https://developers.google.com/maps/documentation/routes/config_trade_offs.md.txt#traffic_aware_optimal) routing preference, routes are calculated accounting for traffic conditions, but no performance optimizations are applied. In this mode, the server performs a more 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:
![The components that make up a route.](https://developers.google.com/static/maps/documentation/places/images/route-leg-places.svg)

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 as *waypoints* 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 more **legs**.

  When passing a route to Text Search, you pass the [route's encoded
  polyline](https://developers.google.com/maps/documentation/routes/traffic_on_polylines) as returned by the [Routes API](https://developers.google.com/maps/documentation/routes). 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 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.

For more information on routes and calculating routes, see the [Routes
API](https://developers.google.com/maps/documentation/routes).

## Calculate the routing summary with a search along route

You can combine **routing summary** calculations with **search along a route** .
In this case, [Text Search (New)](https://developers.google.com/maps/documentation/places/ios-sdk/text-search.md.txt) returns the travel duration and
distance to each place in the response, and then from each place to the final
destination of the route. Think of this calculation as providing a travel
duration and distance if you detour from the specified route to travel to a
place in the search results, and then continue on to the final destination.

For example, consider the following route from the origin to the destination as
calculated by the Routes API. Pass this route to the Text Search (New) API along
with your search criteria.
![Route from the origin waypoint to the destination with detour to search
result.](https://developers.google.com/static/maps/documentation/places/images/travelTimeSearchAlongRoute.svg)

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 duration
and distance required to detour to that place as a **two-leg trip**:

- The first leg contains the travel duration and distance from the route **origin** to the **place**. In this example, from the origin to place A.
- The second leg contains the travel duration and distance from the **place** to the route **destination**. In this example, from A to the destination.

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

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

**Detour duration** is the **duration difference** between the **original trip**
(from the origin to the destination) and the **new trip** (from the origin to
the destination **through** A):
$$ t_{detour} = t_{OA} + t_{AD} - t_{OD} $$

**Detour distance** is the **distance difference** between the **original trip**
(from the origin to the destination) and the **new trip** (from the origin to
the destination **through** A):
$$ s_{detour} = s_{OA} + s_{AD} - s_{OD} $$