API V3 Places Library

Note: The Google Maps Javascript API Version 3 documented within these pages is now the official Javascript API. Version 2 of this API has been officially deprecated as per our deprecation policy. We encourage you to migrate your code to this newly updated and enhanced version!

The Google Places JavaScript library's functions 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.

Title

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

<script type="text/javascript" src="http://maps.googleapis.com/maps/api/js?
    libraries=places&sensor=true_or_false"></script>

See Libraries in the V3 Maps API for more information.

Place Searches

To find Places within a specified area, the Places library provides the search() method. This method returns an array of Places that meet the location criteria - either a LatLngBounds, or a LatLng object representing a center point, and a radius value around that point in which to search.

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.

Place Search Requests

Place Searches are initiated with a call to the PlacesService's search() method.

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

This method takes a request with the following fields:

  • Either of:
    • bounds, which must be a google.maps.LatLngBounds object defining the rectangle in which to search; or
    • a location and radius; the former takes a google.maps.LatLng object, and the radius takes a simple integer, representing the circle's radius in meters.
  • types (optional) — An array containing one or more of the supported types listed in the Google Places API: Supported Place Types list. The service will return results that match any of the specified types.
  • name (optional) — A term to be matched against the names of Places. Results will be restricted to those containing the passed name value. When a name is included, the area being searched may be broadened, to ensure a suitable number of results. Note that a Place may have additional names associated with it, beyond its listed name. The API will try to match the passed name value against all of these names; as a result, Places may be returned in the results whose listed names do not match the search term, but whose associated names do.

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

Supported Places Types

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, its reference property can be used to request additional details about that Place, including full address information and user ratings.

Place Details Requests

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

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

This method takes a request, containing the desired Place's reference value.

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 = {
    reference: 'CnRkAAAAGnBVNFDeQoOQHzgdOpOqJNV7K9-c5IQrWFUYD9TNhUmz5- 
    aHhfqyKH0zmAcUlkqVCrpaKcV8ZjGQKzB6GXxtzUYcP-muHafGsmW
    -1CwjTPBCmK43AZpAwW0FRtQDQADj3H2bzwwHVIXlQAiccm7r4xIQmjt
    _Oqm2FejWpBxLWs3L_RoUbharABi5FMnKnzmRL2TGju6UA4k'
};

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

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

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.

Place Details Results

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

  • name: The Place's name.
  • vicinity: A fragment of the Place's address for disambiguation (usually street name and locality).
  • types: An array of types for this Place (e.g., ["political", "locality"] or ["restaurant", "establishment"]).
  • formatted_phone_number: The Place's phone number, formatted according to the number's regional convention.
  • formatted_address: The Place's full address.
  • address_components: The collection of address components for this Place's location. See the Geocoding service's Address Component Types section for more details.
  • geometry: The Place's geometry-related information. This includes:
    • location provides the latitude and longitude of the Place.
    • viewport defines the preferred viewport on the map when viewing this Place.
  • rating: The Place's rating, from 0.0 to 5.0, based on user reviews.
  • url: URL of the associated Google Place Page.
  • icon: URL to an image resource that can be used to represent this Place's type.
  • html_attributions: Attribution text to be displayed for this Place result.
  • reference: contains a token that can be used to query the Details service in future. This token may differ from the reference used in the request to the Details service. It is recommended that stored references for Places be regularly updated. Although this token uniquely identifies the Place, the converse is not true: a Place may have many valid reference tokens.
  • id: contains a unique identifier denoting this place. This identifier may not be used to retrieve information about this place, but can be used to consolidate data about this Place, and to verify the identity of a Place across separate searches. As ids can occasionally change, it's recommended that the stored id for a Place be compared with the id returned in later Details requests for the same Place, and updated if necessary.