In this document, you will look into how to use [Nearby Search (New)
API](https://developers.google.com/maps/documentation/places/web-service/search-nearby-new)
to build a simple and cost effective local discovery experience.

A local discovery experience shows users key places of interest near a location
you specify when searching for a hotel or a real estate. It often consists of an
interactive map, with an additional panel containing a place chooser and a
gallery of photos. You will be presented with different Google Maps Platform
products and capabilities to enhance the experience with interactivity.

![sample local discovery](https://developers.google.com/static/maps/architecture/improved-cost-effective-local-discovery/images/sample.png)

## Use cases

Now let's understand what elements of the local discovery integration drive user
value:

- **Discovery** - Give users an overview of what is around a single location by surfacing relevant places of various types.
- **Interactivity** - Empower users to select a place and dynamically refresh the data relative to that place.
- **Visualization** - Provide places reviews, photos and walking time and distance for the users to quickly understand if it fits their needs.

## Reference architecture

![alt_text](https://developers.google.com/static/maps/architecture/improved-cost-effective-local-discovery/images/arch.png "A reference architecture for local discovery using the Nearby Search (New) API")

## Local discovery

There are many ways to create a local discovery experience. The following
integration is a **custom example** of a user experience that leverages well
known Google Maps Platform APIs as well as some exciting new features. If you
wish to have a templated approach to local discovery you can use [Web
Components](https://github.com/googlemaps/extended-component-library/tree/main/place_overview).

## Sample application

<iframe style="width:100%; height:354px !important" src="https://maps-cat-local.ew.r.appspot.com/"></iframe>

## Sample walkthrough

You will find in the table below the sample application broken into steps
together with a description of the technical implementation with Google Maps
Platform APIs.

### 1. Search for a location with Places Autocomplete

- Load **Maps Javascript API**.
- **Places Autocomplete** query or pick location on the map.

![sample autocomplete](https://developers.google.com/static/maps/architecture/improved-cost-effective-local-discovery/images/autocomplete.png)

### 2. Surface local points of interest using Nearby Search (New) API

- Popularity ranking (more relevant results) or Distance ranking.
- `includedTypes`, `excludedTypes` ; if you are a hotel you can exclude "lodging" type, and include only suited types, ie: "restaurant, cafe, park, tourist_attraction".
- Leverage `includedPrimaryTypes`, `excludedPrimaryTypes` for even more control over results.
- \`locationRestriction to avoid insufficient number of results or too far away places ; in case of ZERO results, broaden the circle / rectangle size prior to display results.

![sample nearby places](https://developers.google.com/static/maps/architecture/improved-cost-effective-local-discovery/images/nearby-places.png)

Query sample when **booking a hotel** with Data fields requested:

- Basic (`displayName`, `types`, `openingHours`, `formattedAddress`)
- Contact (`websiteUri`, `nationalPhoneNumber`, `internationalPhoneNumber`)
- Preferred (`reviews`, `priceLevel`, `userRatingCount`)

```
 { "includedTypes": ["restaurant","cafe","park"], "excludedTypes":
["lodging","convenience_store"], "includedPrimaryTypes":
["restaurant","tourist_attraction","airport"], "excludedPrimaryTypes":
["lodging"], "maxResultCount": 20, "locationRestriction": { "circle": {
"center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 500.0 } } }
```

Query sample when **searching a real estate** with Data fields requested:

- Basic (`displayName`, `types`, `openingHours`, `formattedAddress`)

```
 { "includedTypes": ["school","transport","bus","convenience_store"],
"excludedTypes": ["lodging"], "includedPrimaryTypes":
["restaurant","tourist_attraction","airport"], "excludedPrimaryTypes":
["lodging"], "maxResultCount": 20, "locationRestriction": { "circle": {
"center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 500.0 } } }
```

### 3. Add interactivity with Dynamic Maps and Directions API

- Up to date **leg and steps** by querying **[Directions
  API](https://developers.google.com/maps/documentation/directions/overview)**. \* Use time in the next section.

![sample directions](https://developers.google.com/static/maps/architecture/improved-cost-effective-local-discovery/images/directions.png)

### 4. Display detailed information of the place upon interaction

1. **Description** : `displayName`, `types`, `rating`, `userRatingCount`,
   `priceLevel`.

   **Time**: coming from the previous Directions API query.
2. **Reviews** : `reviews[i].author`, `reviews[i].rating`,`reviews[i].text`.

3. **Images** : during *Unrestricted Preview of Nearby Search (New) API* , you
   will have to query [Places
   Details](https://developers.google.com/maps/documentation/places/web-service/details)
   with `place.id` to get
   [photo_reference](https://developers.google.com/maps/documentation/places/web-service/details#Place-photos)
   to then query one at a time in your experience

![places details](https://developers.google.com/static/maps/architecture/improved-cost-effective-local-discovery/images/nearby-places-details.png)

### Queries count and cost associated

- [Maps JavaScript
  API](https://developers.google.com/maps/documentation/javascript/usage-and-billing#pricing-for-product): 1 map at load of the experience.
- Places Autocomplete API: 1 query every character typed (if using the [Autocomplete
  Widget](https://developers.google.com/maps/documentation/javascript/place-autocomplete)), it can be customised.
- [Nearby Search (New)
  API](https://developers.google.com/maps/documentation/places/web-service/search-nearby-new): 1 query every 20 places displayed. Different billing according to [Place
  data](https://developers.google.com/maps/documentation/places/web-service/usage-and-billing#data-skus) that are part of the query response.
- [Directions
  API](https://developers.google.com/maps/documentation/directions/usage-and-billing#pricing-for-product): 1 query every place selected by the user.
- [Place Photo
  API](https://developers.google.com/maps/documentation/places/web-service/usage-and-billing#places-photo-new-ent-sku): 1 query every photo displayed.

## Conclusion

A local discovery experience is a powerful way to deliver user value. This
demonstration implementation has many features you are likely to include when
creating such an experience on Google Maps Platform with special capabilities
from the [Nearby Search (New) API](https://developers.google.com/maps/documentation/places/web-service/search-nearby-new).

## Next steps

Suggested further reading:

- [Web Components in the Maps JavaScript API](https://developers.google.com/maps/documentation/web-components/overview)
- [Places Autocomplete Optimization](https://developers.google.com/maps/documentation/places/web-service/autocomplete#best-practices)
- Other [Places Services](https://developers.google.com/maps/documentation/places/web-service/overview.md.txt)
- Leave feedback below.

## Contributors

Principal authors:

[Thomas Anglaret](https://www.linkedin.com/in/thomas-anglaret/) \| Google Maps
Platform Solutions Engineer