Places Library (original) (raw)

Skip to main content

Places Library

Overview

The functions in the Places Library, Maps JavaScript API enable your application to search for places (defined in this API as establishments, geographic locations, or prominent points of interest) contained within a defined area, such as the bounds of a map, or around a fixed point.

The Places API offers an autocomplete feature which you can use to give your applications the type-ahead-search behavior of the Google Maps search field. When a user starts typing an address, autocomplete will fill in the rest. For more information, see theautocomplete documentation.

Getting started

If you are unfamiliar with the Maps JavaScript API or with JavaScript, we recommend reviewing JavaScript andGet an API Key prior to getting started.

Loading the library

The Places service is a self-contained library, separate from the main Maps JavaScript API code. To use the functionality contained within this library, you must first load it using the libraries parameter in the Maps API bootstrap URL:

See the Libraries Overview for more information.

Add Places API to the API key's API restrictions list

Applying API restrictions to your keys limits usage of the API key to one or more APIs or SDKs. Requests to an API or SDK associated with the API key will be processed. Requests to an API or SDK not associated with the API key will fail. To restrict an API key for use with the Places Library, Maps JavaScript API:

  1. Go to the Google Cloud console.
  2. Click the project drop-down and select the project that contains the API key you want to secure.
  3. Click the menu button and select Google Maps Platform > Credentials.
  4. On the Credentials page, click the name of the API key that you want to secure.
  5. On the Restrict and rename API key page, set the restrictions:
    • API restrictions
      • Select Restrict key.
      • Click Select APIs and select both Maps JavaScript API and Places API.
        (If either of the APIs is not listed, you need to enable it.)
  6. Click SAVE.

Usage limits and policies

Quotas

The Places Library shares a usage quota with Places API as described in the Usage Limits documentation for Places API.

Policies

Use of the Places Library, Maps JavaScript API must be in accordance with thepolicies described for the Places API.

Place Searches

With the Places service you can perform the following kinds of searches:

The information returned can include establishments — such as restaurants, stores, and offices — as well as 'geocode' results, which indicate addresses, political areas such as towns and cities, and other points of interest.

Find Place requests

A Find Place request lets you search for a place either by text query or phone number. There are two types of Find Place request:

Find Place from Query

Find Place from Query takes a text input and returns a place. The input can be any kind of Place data, for example a business name or address. To make a Find Place from Query request, call the PlacesService'sfindPlaceFromQuery()method, which takes the following parameters:

You must also pass a callback method to findPlaceFromQuery(), to handle the results object and google.maps.places.PlacesServiceStatusresponse.

The following example shows a call to findPlaceFromQuery(), searching for "Museum of Contemporary Art Australia", and including thename and geometry fields.

var map; var service; var infowindow;

function initMap() { var sydney = new google.maps.LatLng(-33.867, 151.195);

infowindow = new google.maps.InfoWindow();

map = new google.maps.Map( document.getElementById('map'), {center: sydney, zoom: 15});

var request = { query: 'Museum of Contemporary Art Australia', fields: ['name', 'geometry'], };

var service = new google.maps.places.PlacesService(map);

service.findPlaceFromQuery(request, function(results, status) { if (status === google.maps.places.PlacesServiceStatus.OK) { for (var i = 0; i < results.length; i++) { createMarker(results[i]); } map.setCenter(results[0].geometry.location); } }); }

View example

Find Place from Phone Number

Find Place from Phone Number takes a phone number and returns a place. To make a Find Place from Phone Number request, call thePlacesService's findPlaceFromPhoneNumber()method, which takes the following parameters:

You must also pass a callback method to findPlaceFromPhoneNumber(), to handle the results object and google.maps.places.PlacesServiceStatusresponse.

Fields (Find Place methods)

Use the fields parameter to specify an array of place data types to return. For example: fields: ['formatted_address', 'opening_hours', 'geometry']. Use a dot when specifying compound values. For example: opening_hours.weekday_text.

Fields correspond to [Place Search results](/places/web- service/search#PlaceSearchResults), and are divided into three billing categories: Basic, Contact, and Atmosphere. Basic fields are billed at base rate, and incur no additional charges. Contact and Atmosphere fields are billed at a higher rate. See the pricing sheetfor more information. Attributions (html_attributions) are always returned with every call, regardless of whether the field has been requested.

Basic

The Basic category includes the following fields:
business_status, formatted_address, geometry,icon,icon_mask_base_uri, icon_background_color,name, permanently_closed (deprecated),photos, place_id, plus_code, types

Contact

The Contact category includes the following field:opening_hours
(deprecatedin the Places Library, Maps JavaScript API. Use a Place Details request to get theopening_hours results).

Atmosphere

The Atmosphere category includes the following fields:price_level, rating, user_ratings_total

The findPlaceFromQuery() andfindPlaceFromPhoneNumber() methods each take the same set of fields, and can return the same fields in their respective responses.

Set location bias (Find Place methods)

Use the locationBias parameter to make Find Place favor results in a particular area. You can set locationBias in the following ways:

Bias results to a specific area:

locationBias: {lat: 37.402105, lng: -122.081974}

Define a rectangular area to search:

locationBias: {north: 37.41, south: 37.40, east: -122.08, west: -122.09}

You can also use a LatLngBounds.

Define a radius to search (in meters), centered on a particular area:

locationBias: {radius: 100, center: {lat: 37.402105, lng: -122.081974}}

Nearby Search Requests

A Nearby Search lets you search for places within a specified area by keyword or type. A Nearby Search must always include a location, which can be specified in one of two ways:

A Places Nearby search is initiated with a call to the PlacesService's nearbySearch() method, which will return an array of PlaceResult objects. Note that the nearbySearch() method replaces the search() method as of version 3.9.

service = new google.maps.places.PlacesService(map); service.nearbySearch(request, callback);

This method takes a request with the following fields:

You must also pass a callback method to nearbySearch(), to handle the results object andgoogle.maps.places.PlacesServiceStatus response.

var map; var service; var infowindow;

function initialize() { var pyrmont = new google.maps.LatLng(-33.8665433, 151.1956316);

map = new google.maps.Map(document.getElementById('map'), { center: pyrmont, zoom: 15 });

var request = { location: pyrmont, radius: 500, type: 'restaurant' };

service = new google.maps.places.PlacesService(map); service.nearbySearch(request, callback); }

function callback(results, status) { if (status == google.maps.places.PlacesServiceStatus.OK) { for (var i = 0; i < results.length; i++) { createMarker(results[i]); } } }

View example

Text Search Requests

The Google Places Text Search service is a web service that returns information about a set of places based on a string — for example "pizza in New York" or "shoe stores near Ottawa". The service responds with a list of places matching the text string and any location bias that has been set. The search response will include a list of places. You can send a Place Details request for more information about any of the places in the response.

Text Searches are initiated with a call to thePlacesService's textSearch() method.

service = new google.maps.places.PlacesService(map); service.textSearch(request, callback);

This method takes a request with the following fields:

You must also pass a callback method to textSearch(), to handle the results object and agoogle.maps.places.PlacesServiceStatus response.

var map; var service; var infowindow;

function initialize() { var pyrmont = new google.maps.LatLng(-33.8665433,151.1956316);

map = new google.maps.Map(document.getElementById('map'), { center: pyrmont, zoom: 15 });

var request = { location: pyrmont, radius: 500, query: 'restaurant' };

service = new google.maps.places.PlacesService(map); service.textSearch(request, callback); }

function callback(results, status) { if (status == google.maps.places.PlacesServiceStatus.OK) { for (var i = 0; i < results.length; i++) { var place = results[i]; createMarker(results[i]); } } }

Search Responses

Status Codes

The PlacesServiceStatus response object contains the status of the request, and may contain debugging information to help you track down why the place request failed. Possible status values are:

Place Search Results

The findPlace(), nearbySearch() andtextSearch() functions return an array of PlaceResult objects.

Each PlaceResult object may include the following properties:

Accessing Additional Results

By default, each place search returns up to 20 results per query. However, each search can return as many as 60 results, split across three pages. Additional pages are available via the PlaceSearchPagination object. In order to access additional pages you must capture thePlaceSearchPagination object via a callback function. ThePlaceSearchPagination object is defined as:

To see the next set of results, call nextPage. Each page of results must be displayed before displaying the next page of results. Note that each search counts as a single request against your usage limits.

The example below demonstrates how to alter your callback function to capture the PlaceSearchPagination object, so that you can issue multiple search requests.

Place Details

In addition to providing a list of places within an area, the Places service can also return detailed information about a specific place. Once a place has been returned in a place search response, itsplace ID can be used to request additional details about that place, such as its complete address, phone number, user rating and reviews, etc.

Place Details Requests

Place Details are requested with a call to the service'sgetDetails() method.

service = new google.maps.places.PlacesService(map); service.getDetails(request, callback);

This method takes a request, containing the desired place'splaceId, and fields indicating which types of Places data to return. Learn more about how to reference a place with a place ID.

It also takes a callback method, which needs to handle the status code passed in the google.maps.places.PlacesServiceStatus response, as well as the google.maps.places.PlaceResult object.

var request = { placeId: 'ChIJN1t_tDeuEmsRUsoyG83frY4', fields: ['name', 'rating', 'formatted_phone_number', 'geometry'] };

service = new google.maps.places.PlacesService(map); service.getDetails(request, callback);

function callback(place, status) { if (status == google.maps.places.PlacesServiceStatus.OK) { createMarker(place); } }

View example

Fields (Place details)

The fields parameter takes an array of strings (field names).

Use the fields parameter to specify an array of place data types to return. For example: fields: ['address_components', 'opening_hours', 'geometry']. Use a dot when specifying compound values. For example: opening_hours.weekday_text.

Fields correspond to Place Details results, and are divided into three billing categories: Basic, Contact, and Atmosphere. Basic fields are billed at base rate, and incur no additional charges. Contact and Atmosphere fields are billed at a higher rate. See the pricing sheetfor more information. Attributions (html_attributions) are always returned with every call, regardless of whether it has been requested.

Basic

The Basic category includes the following fields:
address_components, adr_address, business_status,formatted_address, geometry, icon,icon_mask_base_uri, icon_background_color,name,permanently_closed (deprecated),photo, place_id, plus_code, type,url, utc_offset (deprecatedin the Places Library, Maps JavaScript API), utc_offset_minutes,vicinity

Contact

The Contact category includes the following fields:
formatted_phone_number, international_phone_number,opening_hours, website

Atmosphere

The Atmosphere category includes the following fields:price_level, rating, reviews,user_ratings_total

Learn more aboutplace fields. For more information about how Place data requests are billed, seeUsage and Billing.

Place Details Responses

Status Codes

The PlacesServiceStatus response object contains the status of the request, and may contain debugging information to help you track down why the Place Details request failed. Possible status values are:

Place Details Results

A successful getDetails() call returns a PlaceResult object with the following properties:

Note: Multidimensional ratings may not be available for all locations. If there are too few reviews then the details response will either include a legacy rating on a 0.0 to 5.0 scale (if available) or no rating at all.

Referencing a Place with a Place ID

A place ID is a unique reference to a place on a Google Map. Place IDs are available for most locations, including businesses, landmarks, parks, and intersections.

To use a place ID in your app you must first look up the ID, which is available in PlaceResult of a Place Search or Details request. You can then use this place ID to look upPlace Details.

Place IDs are exempt from the caching restrictions stated in Section 3.2.3(b) of the Google Maps Platform Terms of Service. You can therefore store place ID values for later use. For best practises when storing place IDs, see theplace ID overview.

var map;

function initialize() { // Create a map centered in Pyrmont, Sydney (Australia). map = new google.maps.Map(document.getElementById('map'), { center: {lat: -33.8666, lng: 151.1958}, zoom: 15 });

// Search for Google's office in Australia. var request = { location: map.getCenter(), radius: '500', query: 'Google Sydney' };

var service = new google.maps.places.PlacesService(map); service.textSearch(request, callback); }

// Checks that the PlacesServiceStatus is OK, and adds a marker // using the place ID and location from the PlacesService. function callback(results, status) { if (status == google.maps.places.PlacesServiceStatus.OK) { var marker = new google.maps.Marker({ map: map, place: { placeId: results[0].place_id, location: results[0].geometry.location } }); } }

google.maps.event.addDomListener(window, 'load', initialize);

Place Photos

The Place Photo feature allows you to add high quality photographic content to your site. The Photo service gives you access to the millions of photos stored in the Places and Google+ Local database. When you get place information using a Place Details request, photo references will be returned for relevant photographic content. The Nearby Search and Text Search requests also return a single photo reference per place, when relevant. Using the Photo service you can then access the referenced photos and resize the image to the optimal size for your application.

An array of PlacePhoto objects will be returned as part of thePlaceResult object for any getDetails(),textSearch() ornearbySearch() request made against a PlacesService.

Note: The number of photos returned varies by request.

You can request the URL for the associated image by calling thePlacePhoto.getUrl() method, and passing a validPhotoOptions object. The PhotoOptions object allows you to specify the maximum desired height and width of the image. If you specify a value for both maxHeight and a maxWidth, the photo service will resize the image to the smaller of the two sizes, while maintaining the original aspect ratio.

The following code snippet accepts a place object, and adds a marker to the map if a photo exists. The default marker image is replaced by a small version of the photo.

function createPhotoMarker(place) { var photos = place.photos; if (!photos) { return; }

var marker = new google.maps.Marker({ map: map, position: place.geometry.location, title: place.name, icon: photos[0].getUrl({maxWidth: 35, maxHeight: 35}) }); }

Photos returned by the Photo service are sourced from a variety of locations, including business owners and user contributed photos. In most cases, these photos can be used without attribution, or will have the required attribution included as a part of the image. However, if the returnedphoto element includes a value in thehtml_attributions field, you must include the additional attribution in your application wherever you display the image.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-06-12 UTC.