Places Library

1. Overview
2. Loading the Library
   • Logo Requirements
3. Place Searches
   1. Nearby Search Requests
   2. Text Search Requests
   3. Radar Search
   4. Search Responses
   5. Accessing Additional Results
4. Place Details
   1. Place Details Requests
   2. Place Details Responses
5. Referencing a Place with a Place ID
6. Place Photos

Overview

The functions in the Google Places JavaScript library 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 Google 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 the autocomplete documentation.

Loading the Library

The Places service is 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="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places"></script>

See the Libraries Overview for more information.

Logo Requirements

If your application displays Google Places API data on a map, that map must be provided by Google.

If your application displays Google Places API data on a page or view that does not also display a Google Map, you must show a "Powered by Google" logo with that data. For example, if your application displays a list of places on one tab, and a Google Map with those places on another tab, the first tab must show the "Powered by Google" logo.

For use on a white background	For use on any non-white background

The following ZIP file contains the "Powered by Google" logo in the correct sizes for desktop, Android and iOS applications. You may not resize or modify these logos in any way.

Download: powered-by-google.zip

Place Searches

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

• Nearby Search returns a list of nearby places based on a user's location.
• Text Search returns a list of nearby places based on a search string, eg. "Pizza".
• Radar Search returns a large list of places within a specified search radius, but with less detail than either Nearby Search or Text Search.
• Place Details requests return more detailed information about a specific place, including user reviews.

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.

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 LatLngBounds.
• a circular area defined as the combination of the location property — specifying the center of the circle as a LatLng object — and a radius, measured in meters.

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:

• Either of:
  • bounds, which must be a google.maps.LatLngBounds object defining the rectangular search area; or
  • a location and a radius; the former takes a google.maps.LatLng object, and the latter takes a simple integer, representing the circle's radius in meters. The maximum allowed radius is 50 000 meters. Note that when rankBy is set to DISTANCE, you must specify a location but you cannot specify a radius or bounds.
• keyword (optional) — A term to be matched against all available fields, including but not limited to name, type, and address, as well as customer reviews and other third-party content.
• minPriceLevel and maxPriceLevel (optional) — Restricts results to only those places within the specified range. Valid values range between 0 (most affordable) to 4 (most expensive), inclusive.
• name (optional) — A term to be matched against the names of places. Results will be restricted to those containing the passed name value. 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.
• openNow (optional) — A boolean value, indicating that the Places service should only return those places that are open for business at the time the query is sent. Places that do not specify opening hours in the Google Places database will not be returned if you include this parameter in your query. Setting openNow to false has no effect.
• rankBy (optional) — Specifies the order in which results are listed. Possible values are:
  • google.maps.places.RankBy.PROMINENCE (default). This option sorts results based on their importance. Ranking will favor prominent places within the set radius over nearby places that match but that are less prominent. Prominence can be affected by a place's ranking in Google's index, global popularity, and other factors. When google.maps.places.RankBy.PROMINENCE is specified, the radius parameter is required.
  • google.maps.places.RankBy.DISTANCE. This option sorts results in ascending order by their distance from the specified location (required). Note that you cannot specify a custom bounds and/or radius if you specify RankBy.DISTANCE. When you specify RankBy.DISTANCE, one or more of keyword, name, or type is required.
• type — Restricts the results to places matching the specified type. Only one type may be specified (if more than one type is provided, all types following the first entry are ignored). See the list of supported types.
• types (deprecated) — An array containing one or more supported types. The service will return the best set of results for a given set of types.

You must also pass a callback method to nearbySearch(), to handle the results object and google.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',
    types: ['store']
  };

  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++) {
      var place = results[i];
      createMarker(results[i]);
    }
  }
}

View example (place-search.html)

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 the PlacesService's textSearch() method.

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

This method takes a request with the following fields:

• query (required) The text string on which to search, for example: "restaurant". The Places service will return candidate matches based on this string and order the results based on their perceived relevance. This parameter becomes optional if the type parameter is also used in the search request.
• Optionally:
  • openNow — A boolean value, indicating that the Places service should only return those places that are open for business at the time the query is sent. Places that do not specify opening hours in the Google Places database will not be returned if you include this parameter in your query. Setting openNow to false has no effect.
  • minPriceLevel and maxPriceLevel — Restricts results to only those places within the specified price level. Valid values are in the range from 0 (most affordable) to 4 (most expensive), inclusive.
  • Either of:
    • bounds — A google.maps.LatLngBounds object defining the rectangle in which to search; or
    • a location and a radius — You may bias results to a specified circle by passing a location and a radius parameter. This will instruct the Places service to prefer showing results within that circle. Results outside the defined area may still be displayed. The location takes a google.maps.LatLng object, and the radius takes a simple integer, representing the circle's radius in meters. The maximum allowed radius is 50 000 meters.
  • type — Restricts the results to places matching the specified type. Only one type may be specified (if more than one type is provided, all types following the first entry are ignored). See the list of supported types.
  • types (deprecated) — An array containing one or more supported types. The service will return results that match any of the specified types.

You must also pass a callback method to textSearch(), to handle the results object and a google.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]);
    }
  }
}

Radar Search Requests

A Radar Search lets you search for places within a specified search radius by keyword, type or name. The Radar Search returns more results than a Nearby Search or Text Search, but the results contain fewer fields. You can call PlacesService.getDetails() to get more information about any of the places in the response.

The PlaceResult objects returned by radarSearch() include only the following properties:

• geometry.location
• place_id
• reference (Note: The reference is deprecated in favor of place_id, as described in the deprecation notice on this page.)

A Places Radar Search is initiated with a call to the PlacesService's radarSearch() method, which will return an array of up to 200 PlaceResult objects.

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

This method takes a request with the following fields:

• Either of:
  • bounds, which must be a google.maps.LatLngBounds object defining the rectangular search area; or
  • a location and a radius; the former takes a google.maps.LatLng object, and the latter takes a simple integer, representing the circle's radius in meters. The maximum allowed radius is 50 000 meters.
• At least one of:
  • keyword (optional) — A term to be matched against all available fields, including but not limited to name, type, and address, as well as customer reviews and other third-party content.
  • name (optional) — A term to be matched against the names of places. Results will be restricted to those containing the passed name value. 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.
  • type — Restricts the results to places matching the specified type. Only one type may be specified (if more than one type is provided, all types following the first entry are ignored). See the list of supported types.
  • types (deprecated) — An array containing one or more supported types.The service will return the best set of results for a given set of types.
• Optionally:
  • minPriceLevel and maxPriceLevel (optional) — Restricts results to only those places within the specified price level. Valid values are in the range from 0 (most affordable) to 4 (most expensive), inclusive.
  • openNow — A boolean value, indicating that the Places service should only return those places that are open for business at the time the query is sent. Places that do not specify opening hours in the Google Places database will not be returned if you include this parameter in your query. Setting openNow to false has no effect.

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

// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">

var map;
var infoWindow;
var service;

function initMap() {
  map = new google.maps.Map(document.getElementById('map'), {
    center: {lat: -33.867, lng: 151.206},
    zoom: 15,
    styles: [{
      stylers: [{ visibility: 'simplified' }]
    }, {
      elementType: 'labels',
      stylers: [{ visibility: 'off' }]
    }]
  });

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

  // The idle event is a debounced event, so we can query & listen without
  // throwing too many requests at the server.
  map.addListener('idle', performSearch);
}

function performSearch() {
  var request = {
    bounds: map.getBounds(),
    keyword: 'best view'
  };
  service.radarSearch(request, callback);
}

function callback(results, status) {
  if (status !== google.maps.places.PlacesServiceStatus.OK) {
    console.error(status);
    return;
  }
  for (var i = 0, result; result = results[i]; i++) {
    addMarker(result);
  }
}

function addMarker(place) {
  var marker = new google.maps.Marker({
    map: map,
    position: place.geometry.location,
    icon: {
      url: 'http://maps.gstatic.com/mapfiles/circle.png',
      anchor: new google.maps.Point(10, 10),
      scaledSize: new google.maps.Size(10, 17)
    }
  });

  google.maps.event.addListener(marker, 'click', function() {
    service.getDetails(place, function(result, status) {
      if (status !== google.maps.places.PlacesServiceStatus.OK) {
        console.error(status);
        return;
      }
      infoWindow.setContent(result.name);
      infoWindow.open(map, marker);
    });
  });
}

<div id="map"></div>

html, body {
  height: 100%;
  margin: 0;
  padding: 0;
}
#map {
  height: 100%;
}

<!-- Replace the value of the key parameter with your own API key. -->
<script src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap&libraries=places,visualization" async defer></script>

// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">

var map;
var infoWindow;
var service;

function initMap() {
  map = new google.maps.Map(document.getElementById('map'), {
    center: {lat: -33.867, lng: 151.206},
    zoom: 15,
    styles: [{
      stylers: [{ visibility: 'simplified' }]
    }, {
      elementType: 'labels',
      stylers: [{ visibility: 'off' }]
    }]
  });

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

  // The idle event is a debounced event, so we can query & listen without
  // throwing too many requests at the server.
  map.addListener('idle', performSearch);
}

function performSearch() {
  var request = {
    bounds: map.getBounds(),
    keyword: 'best view'
  };
  service.radarSearch(request, callback);
}

function callback(results, status) {
  if (status !== google.maps.places.PlacesServiceStatus.OK) {
    console.error(status);
    return;
  }
  for (var i = 0, result; result = results[i]; i++) {
    addMarker(result);
  }
}

function addMarker(place) {
  var marker = new google.maps.Marker({
    map: map,
    position: place.geometry.location,
    icon: {
      url: 'http://maps.gstatic.com/mapfiles/circle.png',
      anchor: new google.maps.Point(10, 10),
      scaledSize: new google.maps.Size(10, 17)
    }
  });

  google.maps.event.addListener(marker, 'click', function() {
    service.getDetails(place, function(result, status) {
      if (status !== google.maps.places.PlacesServiceStatus.OK) {
        console.error(status);
        return;
      }
      infoWindow.setContent(result.name);
      infoWindow.open(map, marker);
    });
  });
}

View example (place-radar-search.html).

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:

• ERROR: There was a problem contacting the Google servers.
• INVALID_REQUEST: This request was invalid.
• OK: The response contains a valid result.
• OVER_QUERY_LIMIT: The webpage has gone over its request quota.
• REQUEST_DENIED: The webpage is not allowed to use the PlacesService.
• UNKNOWN_ERROR: The PlacesService request could not be processed due to a server error. The request may succeed if you try again.
• ZERO_RESULTS: No result was found for this request.

Place Search Results

The nearbySearch() and textSearch() functions return an array of PlaceResult objects. The radarSearch() function returns a subset of the fields in the PlaceResult, as described above.

Each PlaceResult object may include the following properties:

• formatted_address is a string containing the human-readable address of this place. Often this address is equivalent to the "postal address". The formatted_address property is only returned for a Text Search.
• 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.
• html_attributions: An array of attributions that you should display when displaying the search results. Each entry in the array contains the HTML text for a single attribution. Note: This is an aggregation of all the attributions for the entire search response. All PlaceResult objects in the response therefore contain identical attribution lists.
• icon: URL to an image resource that can be used to represent this place's type.
• 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. Note: The id is deprecated in favor of place_id, as described in the deprecation notice on this page.
• name: The place's name.
• opening_hours may contain the following information:
  • open_now is a boolean value indicating if the place is open at the current time.
• place_id is a textual identifier that uniquely identifies a place. To retrieve information about the place, pass this identifier in the placeId field of a Place Details request. Learn more about how to reference a place with a place ID.
• rating contains the place's rating, from 0.0 to 5.0, based on aggregated user reviews.
• 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. Note: The reference is deprecated in favor of place_id, as described in the deprecation notice on this page.
• types An array of types for this place (e.g., ["political", "locality"] or ["restaurant", "lodging"]).
• vicinity: A simplified address for the place, including the street name, street number, and locality, but not the province/state, postal code, or country. For example, Google's Sydney, Australia office has a vicinity value of 5/48 Pirrama Road, Pyrmont.

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 the PlaceSearchPagination object via a callback function. The PlaceSearchPagination object is defined as:

• hasNextPage a boolean property that indicates if further results are available. true when there is an additional results page.
• nextPage() a function that will return the next set of results. After executing a search, you must wait two seconds before the next page of results will be available.

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.

// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">

var map;

function initMap() {
  var pyrmont = {lat: -33.866, lng: 151.196};

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

  var service = new google.maps.places.PlacesService(map);
  service.nearbySearch({
    location: pyrmont,
    radius: 500,
    type: ['store']
  }, processResults);
}

function processResults(results, status, pagination) {
  if (status !== google.maps.places.PlacesServiceStatus.OK) {
    return;
  } else {
    createMarkers(results);

    if (pagination.hasNextPage) {
      var moreButton = document.getElementById('more');

      moreButton.disabled = false;

      moreButton.addEventListener('click', function() {
        moreButton.disabled = true;
        pagination.nextPage();
      });
    }
  }
}

function createMarkers(places) {
  var bounds = new google.maps.LatLngBounds();
  var placesList = document.getElementById('places');

  for (var i = 0, place; place = places[i]; i++) {
    var image = {
      url: place.icon,
      size: new google.maps.Size(71, 71),
      origin: new google.maps.Point(0, 0),
      anchor: new google.maps.Point(17, 34),
      scaledSize: new google.maps.Size(25, 25)
    };

    var marker = new google.maps.Marker({
      map: map,
      icon: image,
      title: place.name,
      position: place.geometry.location
    });

    placesList.innerHTML += '<li>' + place.name + '</li>';

    bounds.extend(place.geometry.location);
  }
  map.fitBounds(bounds);
}

<div id="map"></div>
<div id="right-panel">
  <h2>Results</h2>
  <ul id="places"></ul>
  <button id="more">More results</button>
</div>

html, body {
  height: 100%;
  margin: 0;
  padding: 0;
}
#map {
  height: 100%;
}

#right-panel {
  font-family: 'Roboto','sans-serif';
  line-height: 30px;
  padding-left: 10px;
}

#right-panel select, #right-panel input {
  font-size: 15px;
}

#right-panel select {
  width: 100%;
}

#right-panel i {
  font-size: 12px;
}

#right-panel {
  font-family: Arial, Helvetica, sans-serif;
  position: absolute;
  right: 5px;
  top: 60%;
  margin-top: -195px;
  height: 330px;
  width: 200px;
  padding: 5px;
  z-index: 5;
  border: 1px solid #999;
  background: #fff;
}
h2 {
  font-size: 22px;
  margin: 0 0 5px 0;
}
ul {
  list-style-type: none;
  padding: 0;
  margin: 0;
  height: 271px;
  width: 200px;
  overflow-y: scroll;
}
li {
  background-color: #f1f1f1;
  padding: 10px;
  text-overflow: ellipsis;
  white-space: nowrap;
  overflow: hidden;
}
li:nth-child(odd) {
  background-color: #fcfcfc;
}
#more {
  width: 100%;
  margin: 5px 0 0 0;
}

<!-- Replace the value of the key parameter with your own API key. -->
<script src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&libraries=places&callback=initMap" async defer></script>

// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">

var map;

function initMap() {
  var pyrmont = {lat: -33.866, lng: 151.196};

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

  var service = new google.maps.places.PlacesService(map);
  service.nearbySearch({
    location: pyrmont,
    radius: 500,
    type: ['store']
  }, processResults);
}

function processResults(results, status, pagination) {
  if (status !== google.maps.places.PlacesServiceStatus.OK) {
    return;
  } else {
    createMarkers(results);

    if (pagination.hasNextPage) {
      var moreButton = document.getElementById('more');

      moreButton.disabled = false;

      moreButton.addEventListener('click', function() {
        moreButton.disabled = true;
        pagination.nextPage();
      });
    }
  }
}

function createMarkers(places) {
  var bounds = new google.maps.LatLngBounds();
  var placesList = document.getElementById('places');

  for (var i = 0, place; place = places[i]; i++) {
    var image = {
      url: place.icon,
      size: new google.maps.Size(71, 71),
      origin: new google.maps.Point(0, 0),
      anchor: new google.maps.Point(17, 34),
      scaledSize: new google.maps.Size(25, 25)
    };

    var marker = new google.maps.Marker({
      map: map,
      icon: image,
      title: place.name,
      position: place.geometry.location
    });

    placesList.innerHTML += '<li>' + place.name + '</li>';

    bounds.extend(place.geometry.location);
  }
  map.fitBounds(bounds);
}

View example (place-search-pagination.html).

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 place ID can be used to request additional details about that place, such as its complete address, phone number, user rating and reviews, etc. (The place reference can also be used to retrieve place details, but this field is deprecated in favor of place ID, as described in the deprecation notice on this page.)

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 placeId or reference. The reference is deprecated in favor of placeId as described in the deprecation notice on this page. 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'
};

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 (place-details.html)

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:

• ERROR: There was a problem contacting the Google servers.
• INVALID_REQUEST: This request was invalid.
• OK: The response contains a valid result.
• OVER_QUERY_LIMIT: The webpage has gone over its request quota.
• NOT_FOUND The referenced location was not found in the Places database.
• REQUEST_DENIED: The webpage is not allowed to use the PlacesService.
• UNKNOWN_ERROR: The PlacesService request could not be processed due to a server error. The request may succeed if you try again.
• ZERO_RESULTS: No result was found for this request.

Place Details Results

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

• address_components: The collection of address components for this place's location. See the Geocoding service's Address Component Types section for more details.
• formatted_address: The place's full address.
• formatted_phone_number: The place's phone number, formatted according to the number's regional convention.
• 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.
• html_attributions: Attribution text to be displayed for this place result.
• icon: URL to an image resource that can be used to represent this place's type.
• 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. Note: The id is deprecated in favor of place_id, as described in the deprecation notice on this page.
• international_phone_number contains the place's phone number in international format. International format includes the country code, and is prefixed with the plus (+) sign. For example, the international_phone_number for Google's Sydney, Australia office is +61 2 9374 4000.
• name: The place's name.
• utc_offset contains the number of minutes this place’s current timezone is offset from UTC. For example, for places in Sydney, Australia during daylight saving time this would be 660 (+11 hours from UTC), and for places in California outside of daylight saving time this would be -480 (-8 hours from UTC).
• opening_hours contains the following information:
  • open_now is a boolean value indicating if the place is open at the current time.
  • periods[] is an array of opening periods covering seven days, starting from Sunday, in chronological order. Each period contains:
    • open contains a pair of day and time objects describing when the place opens:
      • day a number from 0–6, corresponding to the days of the week, starting on Sunday. For example, 2 means Tuesday.
      • time may contain a time of day in 24-hour hhmm format (values are in the range 0000–2359). The time will be reported in the place’s timezone.
    • close may contain a pair of day and time objects describing when the place closes. Note: If a place is always open, the close section will be missing from the response. Applications can rely on always-open being represented as an open period containing day with value 0 and time with value 0000, and no close.
  • weekday_text is an array of seven strings representing the formatted opening hours for each day of the week. If a language parameter was specified in the Place Details request, the Places Service will format and localize the opening hours appropriately for that language. The ordering of the elements in this array depends on the language parameter. Some languages start the week on Monday while others start on Sunday.
• permanently_closed: a boolean flag indicating whether the place has permanently shut down (value true). If the place is not permanently closed, the flag is absent from the response.
• photos[]: an array of PlacePhoto objects. A PlacePhoto can be used to obtain a photo with the getUrl() method, or you can inspect the object for the following values:
  • height: the maximum height of the image, in pixels.
  • width: the maximum width of the image, in pixels.
  • html_attributions: Attribution text to be displayed with this place photo.
• place_id: A textual identifier that uniquely identifies a place and can be used to retrieve information about the place via a Place Details request. Learn more about how to reference a place with a place ID.
• rating: The place's rating, from 0.0 to 5.0, based on aggregated user reviews.
• 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. Note: The reference is deprecated in favor of place_id, as described in the deprecation notice on this page.
• reviews an array of up to five reviews. Each review consists of several components:
  • aspects[] contains an array of PlaceAspectRating objects, each of which provides a rating of a single attribute of the establishment. The first object in the array is considered the primary aspect. Each PlaceAspectRating is defined as:
    • type the name of the aspect that is being rated. The following types are supported: appeal, atmosphere, decor, facilities, food, overall, quality and service.
    • rating the user's rating for this particular aspect, from 0 to 3.
  • author_name the name of the user who submitted the review. Anonymous reviews are attributed to "A Google user". If a language parameter was set, then the phrase "A Google user" will return a localized string.
  • author_url the URL to the users Google+ profile, if available.
  • language an IETF language code indicating the language used in the user's review. This field contains the main language tag only, and not the secondary tag indicating country or region. For example, all the English reviews are tagged as 'en', and not 'en-AU' or 'en-UK' and so on.
  • rating the user's overall rating for this place. This is a whole number, ranging from 1 to 5.
  • text the user's review. When reviewing a location with Google Places, text reviews are considered optional; therefore, this field may by empty.
• types An array of types for this place (e.g., ["political", "locality"] or ["restaurant", "lodging"]).
• url: URL of the official Google page for this place. This is the Google-owned page that contains the best available information about the place. Applications must link to or embed this page on any screen that shows detailed results about the place to the user.
• vicinity: A simplified address for the place, including the street name, street number, and locality, but not the province/state, postal code, or country. For example, Google's Sydney, Australia office has a vicinity value of 5/48 Pirrama Road, Pyrmont. The vicinity property is only returned for a Nearby Search.
• website lists the authoritative website for this place, such as a business' homepage.

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

Places on a Google Map can be uniquely referenced with their place ID. Place IDs are available for most locations, including businesses, landmarks, parks, and intersections. These IDs are stable, meaning that once you've identified the place ID for a location, you can reuse that value when you next look up that location.

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 later use this place ID to look up Place Details, or to enable Save Attribution in a signed-in map.

Place IDs are exempt from the caching restrictions stated in Section 10.5.d of the Google Maps APIs Terms of Service. You can therefore store place ID values indefinitely.

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 the PlaceResult object for any getDetails(), textSearch() or nearbySearch() request made against a PlacesService.

Note: The number of photos returned varies by request.

• A Nearby Search or a Text Search will return at most one PlacePhoto object.
• Radar Searches do not return any photo information.
• A Details request will return up to ten PlacePhoto objects.

You can request the URL for the associated image by calling the PlacePhoto.getUrl() method, and passing a valid PhotoOptions object. The PhotoOptions object allows you to specify the maximum desired height and width of the image. If you specify a value for both max_height and a max_width, 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})
  });
}