Overview

Select platform: Android iOS JavaScript Web Service
The Places API is a service that accepts HTTP requests for location data through a variety of methods. It returns formatted location data and imagery about establishments, geographic locations, or prominent points of interest.

Why use the Places API

Create location-aware features to make detailed location data easily available to your users. The data available through the Places API is built on one of the most accurate, up-to-date, and comprehensive place models of the real world. Here are example use cases for applications:

  • Display condo rentals within major metropolitan areas with results targeted specifically to cities.
  • Include place details in a pickup or delivery status update.
  • Display a list of parks in an area along with user-submitted photos and reviews.
  • Provide people planning trips with contact information, reviews, and price levels for establishments along the way.

What can you do with the Places API

You can use the Places API to include the following features in your applications:

  • Provide place search results from different types of users queries, such as text input, nearby locations, and ambiguous or categorical user queries.
  • Enable autocomplete features for different search types, either specific text queries or categorical queries.
  • Refine the type of details returned about a place, such as operating hours, a summary, user reviews, and a photo.
  • Add high-quality photos to locations served by your application.

Many Google Maps Platform APIs support place IDs, where the place ID uniquely identifies a place in the Google Places database and on Google Maps. There are many ways to obtain a place ID, including from the Places API, but also from the Geocoding API, Routes API, and Address Validation API.

Once you have a place ID, you can use the Places API to request more details about a particular establishment or point of interest, such as its complete address, phone number, user rating, and reviews.

Choose your version of Places API

Places API supports two API versions: Places API are the existing APIs and Places API (New) are the next generation versions of the APIs.

With the release of Places API (New), your first task is to decide which set of APIs to use. This is true if you are a new customer or an existing customer already using the APIs. Use this guide to learn the key differences between the two APIs.

How the Places API works

Places API (New)

Places API (New) accepts requests as a standard URL with a specific service endpoint, such as /places or places:searchText and returns a JSON response. Places API (New) supports authorization by API key and OAuth token. The following example makes a Place Details request to return the address components for a place ID using an API key:

https://places.googleapis.com/v1/places/GyuEmsRBfy61i59si0?fields=addressComponents&key=YOUR_API_KEY

Places API

Places API accepts requests as a standard URL with a specific service endpoint, such as /place or /photo. The endpoints also accept the type of format specified in the request, either JSON or XML. The service request uses parameters relevant to that specific endpoint to refine the data returned. The following example makes a Place Details request to return the address components for a place ID in JSON format:

https://maps.googleapis.com/maps/api/place/details/json?place_id=ChIJrTLr-GyuEmsRBfy61i59si0&fields=address_components&key=YOUR_API_KEY

In this instance, the service uses the provided place ID to find the requested place and return the address components in JSON format.

Resources

The following table summarizes the resources available through the Places API.

Places API Places API (New) Note
Find Place Text Search (New) There is no new version of Find Place. Text Search (New) has replaced it.
Nearby Search Nearby Search (New) All requests using the existing API that include a text query should use Text Search (New) because Nearby Search (New) does not support text input.
Text Search Text Search (New)
Place Details Place Details (New)
Place Photo Place Photo (New)
Place Autocomplete No Places API (New) version
Query Autocomplete No Places API (New) version

How to use the Places API

The steps below cover a typical use case scenario for using the Places API service. As you build out your solution, you can use additional endpoints, such as Nearby Search and Place Photos.
1 Get setup Start with Set up your Google Cloud project and complete the setup instructions that follow and then learn how to use your API key. For Places API (New), you can also use OAuth tokens.
2 Try a basic text search Issue a simple text search by using Text Search (New) or Text Search.
3 Use the place ID for more details Many Google Maps Platform APIs return a place ID as part of a response. Use the place ID to get details about a place. See Place Details (New) and Place Details.
4 Get a photo for a place The Place Photo service gives you access to the millions of photos stored in the Places database. Use Place Photo (New) or Place Details to access photos for a place.