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.

How the Places API works

The 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. Finally, the service request uses parameters relevant to that specific endpoint to refine the data returned. For example, the following Place Details request for address components works as follows, assuming a return 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 along with the data it returns.

Data resources Data returned Return format
Place search Returns a list of places based on a device location or search string.

See details for Place search responses, Nearby search responses, and Text search responses.

  • JSON
  • XML
Place details Returns more detailed information about a specific place, including user reviews.

See details in Place details responses.

  • JSON
  • XML
Place photos Provides access to the millions of place-related photos stored in Google's Place database.

See details for Place photos response.

  • JSON
  • XML
Place autocomplete Automatically fills in the name and/or address of a place as users type.

See details for Place autocomplete responses.

  • JSON
  • XML
Query autocomplete Provides a query prediction service for text-based geographic searches, returning suggested queries as users type.

See details for Query autocomplete responses.

  • JSON
  • XML

How to use the Places API

The steps below cover a typical use case scenario for using three of the endpoints in the Places API service. As you build out your solution, you can use additional endpoints, such as Nearby Search, Place Photos, and Query Autocomplete.
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.
2 Try a basic text search Once you have an API key, issue a simple text search as indicated in Basic text search examples in the Text search guide.
3 Use a Find Place request Find Place requests return a place ID, along with data fields you request, such as opening hours, address, and photos. See Find Place examples and try one more relevant to your use case.
4 Understand Find Place response basics Explore the data returned from the Find Place response. See Find place responses for details.
5 Use the place ID for more details Find Place responses do not provide all the data available for a particular place. You can use the place ID returned from a Find Place response to get even more details about a place. See Place Details.

Available client libraries

Call this API in the language of your choice through one of the following client libraries:

The Java Client, Python Client, Go Client and Node.js Client for Google Maps Services are community-supported client libraries, open sourced under the Apache 2.0 License. Download them from GitHub, where you can also find installation instructions and sample code.

What's next