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 the autocomplete documentation.

Getting started

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

Enable APIs

Before using the Places library in the Maps JavaScript API, first ensure that the Places API is enabled in the Google Cloud Console, in the same project you set up for the Maps JavaScript API.

To view your list of enabled APIs:

  1. Go to the Google Cloud Console.
  2. Click the Select a project button, then select the same project you set up for the Maps JavaScript API and click Open.
  3. From the list of APIs on the Dashboard, look for Places API.
  4. If you see the Places API in the list, it's already enabled. If the API is not listed, enable it:
    1. At the top of the page, select ENABLE APIS AND SERVICES to display the Library tab. Alternatively, from the left side menu, select Library.
    2. Search for Places API, then select it from the results list.
    3. Select ENABLE. When the process finishes, Places API appears in the list of APIs on the Dashboard.

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:

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&libraries=places&callback=initMap">
</script>

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 the policies 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's findPlaceFromQuery() method, which takes the following parameters:

  • query (required) The text string on which to search, for example: "restaurant" or "123 Main Street". This must be a place name, address, or category of establishments. Any other types of input can generate errors and are not guaranteed to return valid results. The Places API will return candidate matches based on this string and order the results based on their perceived relevance.
  • fields (required) One or more fields specifying the types of Place data to return.
  • locationBias (optional) Coordinates defining the area to search. This can be one of the following:

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

The following example shows a call to findPlaceFromQuery(), searching for "Museum of Contemporary Art Australia", and including the name 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 the PlacesService's findPlaceFromPhoneNumber() method, which takes the following parameters:

  • phoneNumber (required) A phone number, in E.164 format.
  • fields (required) One or more fields specifying the types of Place data to return.
  • locationBias (optional) Coordinates defining the area to search. This can be one of the following:

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

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, 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 sheet for 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
(deprecated in the Places Library, Maps JavaScript API. Use a Place Details request to get the opening_hours results).

Atmosphere

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

The findPlaceFromQuery() and findPlaceFromPhoneNumber() 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 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. The maximum supported diagonal distance for the bounds area is approximately 100,000 meters.
    • 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 Deprecated. Equivalent to keyword. Values in this field are combined with values in the keyword field and passed as part of the same search string.
  • 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.

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',
    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 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" or "123 Main Street". This must be a place name, address, or category of establishments. Any other types of input can generate errors and are not guaranteed to return valid results. 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, which must be a google.maps.LatLngBounds object defining the rectangular search area. The maximum supported diagonal distance for the bounds area is approximately 100,000 meters.
      • 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.

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]);
    }
  }
}

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:

  • 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 findPlace(), nearbySearch() and textSearch() functions return an array of PlaceResult objects.

Each PlaceResult object may include the following properties:

  • business_status indicates the operational status of the place, if it is a business. It can contain one of the following values:
    • OPERATIONAL
    • CLOSED_TEMPORARILY
    • CLOSED_PERMANENTLY
    If no data exists, business_status is not returned.
  • formatted_address is a string containing the human-readable address of this place. The formatted_address property is only returned for a Text Search.

    Often this address is equivalent to the postal address. Note that some countries, such as the United Kingdom, do not allow distribution of true postal addresses due to licensing restrictions.

    The formatted address is logically composed of one or more address components. For example, the address "111 8th Avenue, New York, NY" consists of the following components: "111" (the street number), "8th Avenue" (the route), "New York" (the city) and "NY" (the US state).

    Do not parse the formatted address programmatically. Instead you should use the individual address components, which the API response includes in addition to the formatted address field.

  • 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.
  • permanently_closed (deprecated) is a boolean flag indicating whether the place has shut down either permanently or temporarily (value true). Do not use permanently_closed. Instead, use business_status to get the operational status of businesses.
  • plus_code (see Open Location Code and plus codes) is an encoded location reference, derived from latitude and longitude coordinates, that represents an area: 1/8000th of a degree by 1/8000th of a degree (about 14m x 14m at the equator) or smaller. Plus codes can be used as a replacement for street addresses in places where they do not exist (where buildings are not numbered or streets are not named).

    The plus code is formatted as a global code and a compound code:

    • global_code is a 4 character area code and 6 character or longer local code (849VCWC8+R9).
    • compound_code is a 6 character or longer local code with an explicit location (CWC8+R9, Mountain View, CA, USA). Do not programmatically parse this content.
    Typically, both the global code and compound code are returned. However, if the result is in a remote location (for example, an ocean or desert) only the global code may be returned.
  • 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 returns the URL for a colored 71px x 71px PNG icon.
  • icon_mask_base_uri returns the base URL for a non-colored icon, minus the .svg or .png extension.
  • icon_background_color returns the default HEX color code for the place's category.
  • 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 (Deprecated in the Places Library, Maps JavaScript API, use utc_offset_minutes instead).
  • place_id is a textual identifier that uniquely identifies a place. To retrieve information about the place, pass this identifier in the 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.
  • types An array of types for this place (e.g., ["political", "locality"] or ["restaurant", "lodging"]). This array may contain multiple values, or may be empty. New values may be introduced without prior notice. See the list of supported types.
  • 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.

TypeScript

// 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">

function initMap(): void {
  // Create the map.
  const pyrmont = { lat: -33.866, lng: 151.196 };
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      center: pyrmont,
      zoom: 17,
      mapId: "8d193001f940fde3",
    } as google.maps.MapOptions
  );

  // Create the places service.
  const service = new google.maps.places.PlacesService(map);
  let getNextPage: () => void | false;
  const moreButton = document.getElementById("more") as HTMLButtonElement;

  moreButton.onclick = function () {
    moreButton.disabled = true;

    if (getNextPage) {
      getNextPage();
    }
  };

  // Perform a nearby search.
  service.nearbySearch(
    { location: pyrmont, radius: 500, type: "store" },
    (
      results: google.maps.places.PlaceResult[] | null,
      status: google.maps.places.PlacesServiceStatus,
      pagination: google.maps.places.PlaceSearchPagination | null
    ) => {
      if (status !== "OK" || !results) return;

      addPlaces(results, map);
      moreButton.disabled = !pagination || !pagination.hasNextPage;

      if (pagination && pagination.hasNextPage) {
        getNextPage = () => {
          // Note: nextPage will call the same handler function as the initial call
          pagination.nextPage();
        };
      }
    }
  );
}

function addPlaces(
  places: google.maps.places.PlaceResult[],
  map: google.maps.Map
) {
  const placesList = document.getElementById("places") as HTMLElement;

  for (const place of places) {
    if (place.geometry && place.geometry.location) {
      const 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),
      };

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

      const li = document.createElement("li");

      li.textContent = place.name!;
      placesList.appendChild(li);

      li.addEventListener("click", () => {
        map.setCenter(place.geometry!.location!);
      });
    }
  }
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

JavaScript

// 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">
function initMap() {
  // Create the map.
  const pyrmont = { lat: -33.866, lng: 151.196 };
  const map = new google.maps.Map(document.getElementById("map"), {
    center: pyrmont,
    zoom: 17,
    mapId: "8d193001f940fde3",
  });
  // Create the places service.
  const service = new google.maps.places.PlacesService(map);
  let getNextPage;
  const moreButton = document.getElementById("more");

  moreButton.onclick = function () {
    moreButton.disabled = true;
    if (getNextPage) {
      getNextPage();
    }
  };

  // Perform a nearby search.
  service.nearbySearch(
    { location: pyrmont, radius: 500, type: "store" },
    (results, status, pagination) => {
      if (status !== "OK" || !results) return;

      addPlaces(results, map);
      moreButton.disabled = !pagination || !pagination.hasNextPage;
      if (pagination && pagination.hasNextPage) {
        getNextPage = () => {
          // Note: nextPage will call the same handler function as the initial call
          pagination.nextPage();
        };
      }
    },
  );
}

function addPlaces(places, map) {
  const placesList = document.getElementById("places");

  for (const place of places) {
    if (place.geometry && place.geometry.location) {
      const 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),
      };

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

      const li = document.createElement("li");

      li.textContent = place.name;
      placesList.appendChild(li);
      li.addEventListener("click", () => {
        map.setCenter(place.geometry.location);
      });
    }
  }
}

window.initMap = initMap;
index.js
View example

Try Sample

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.

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, 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 sheet for 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 (deprecated in 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 about place fields. For more information about how Place data requests are billed, see Usage 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:

  • 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: An array containing the separate components applicable to this address.

    Each address component typically contains the following fields:

    • types[] is an array indicating the type of the address component. See the list of supported types.
    • long_name is the full text description or name of the address component as returned by the Geocoder.
    • short_name is an abbreviated textual name for the address component, if available. For example, an address component for the state of Alaska may have a long_name of "Alaska" and a short_name of "AK" using the 2-letter postal abbreviation.

    Note the following facts about the address_components[] array:

    • The array of address components may contain more components than the formatted_address.
    • The array does not necessarily include all the political entities that contain an address, apart from those included in the formatted_address. To retrieve all the political entities that contain a specific address, you should use reverse geocoding, passing the latitude/longitude of the address as a parameter to the request.
    • The format of the response is not guaranteed to remain the same between requests. In particular, the number of address_components varies based on the address requested and can change over time for the same address. A component can change position in the array. The type of the component can change. A particular component may be missing in a later response.
  • business_status indicates the operational status of the place, if it is a business. It can contain one of the following values:
    • OPERATIONAL
    • CLOSED_TEMPORARILY
    • CLOSED_PERMANENTLY
    If no data exists, business_status is not returned.
  • formatted_address: The human-readable address of this place.

    Often this address is equivalent to the postal address. Note that some countries, such as the United Kingdom, do not allow distribution of true postal addresses due to licensing restrictions.

    The formatted address is logically composed of one or more address components. For example, the address "111 8th Avenue, New York, NY" consists of the following components: "111" (the street number), "8th Avenue" (the route), "New York" (the city) and "NY" (the US state).

    Do not parse the formatted address programmatically. Instead you should use the individual address components, which the API response includes in addition to the formatted address field.

  • 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.
  • permanently_closed (deprecated) is a boolean flag indicating whether the place has shut down either permanently or temporarily (value true). Do not use permanently_closed. Instead, use business_status to get the operational status of businesses.
  • plus_code (see Open Location Code and plus codes) is an encoded location reference, derived from latitude and longitude coordinates, that represents an area: 1/8000th of a degree by 1/8000th of a degree (about 14m x 14m at the equator) or smaller. Plus codes can be used as a replacement for street addresses in places where they do not exist (where buildings are not numbered or streets are not named).

    The plus code is formatted as a global code and a compound code:

    • global_code is a 4 character area code and 6 character or longer local code (849VCWC8+R9).
    • compound_code is a 6 character or longer local code with an explicit location (CWC8+R9, Mountain View, CA, USA). Do not programmatically parse this content.
    Typically, both the global code and compound code are returned. However, if the result is in a remote location (for example, an ocean or desert) only the global code may be returned.
  • 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.
  • 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 Deprecated in the Places Library, Maps JavaScript API, use utc_offset_minutes instead.
  • utc_offset_minutes 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 (Deprecated in the Places Library, Maps JavaScript API; use opening_hours.isOpen() instead. See this video for how to use isOpen with Place Details.) is a boolean value indicating whether 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 (deprecated) is a boolean flag indicating whether the place has shut down either permanently or temporarily (value true). Do not use permanently_closed. Instead, use business_status to get the operational status of businesses.
  • 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.
  • 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"]). This array may contain multiple values, or may be empty. New values may be introduced without prior notice. See the list of supported types.
  • 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.

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 up Place 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 the place 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 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.
  • 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 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 returned photo element includes a value in the html_attributions field, you must include the additional attribution in your application wherever you display the image.