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.

Load 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 thelibraries 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

1. Go to theGoogle 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 selectGoogle Maps Platform > Credentials.
4. On theCredentials page, click the name of the API key that you want to secure.
5. On theRestrict and rename API key page, set the restrictions:
   
   • API restrictions
   • SelectRestrict key.
   • ClickSelect APIs and select bothMaps JavaScript API andPlaces API.
     (If either of the APIs is not listed, you need toenable it.)
6. ClickSAVE.

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:

• Find Place from Query returns a place based on a text query (for example, the name or address of a place).
• Find Place from Phone Number returns a place based on a phone number.
• 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".
• 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.

Find Place requests

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

• Find Place from Query
• Find Place from Phone Number

Find Place from Query

Find Place from Query takes a text input and returns a place. The input canbe any kind of Place data, for example a business name or address. To make aFind Place from Query request, call thePlacesService'sfindPlaceFromQuery()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 morefields specifying the types of Place data to return.
• locationBias (optional) Coordinates defining the area to search. This can be one of the following:
  • A set of lat/lng coordinates specified asLatLngLiteral orLatLng object
  • Rectangular bounds (two lat/lng pairs, or aLatLngBounds object)
  • Radius (in meters) centered on a lat/lng

You must also pass a callback method tofindPlaceFromQuery(),to handle the results object andgoogle.maps.places.PlacesServiceStatusresponse.

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

varmap;varservice;varinfowindow;functioninitMap(){varsydney=newgoogle.maps.LatLng(-33.867,151.195);infowindow=newgoogle.maps.InfoWindow();map=newgoogle.maps.Map(document.getElementById('map'),{center:sydney,zoom:15});varrequest={query:'Museum of Contemporary Art Australia',fields:['name','geometry'],};varservice=newgoogle.maps.places.PlacesService(map);service.findPlaceFromQuery(request,function(results,status){if(status===google.maps.places.PlacesServiceStatus.OK){for(vari=0;i<results.length;i++){createMarker(results[i]);}map.setCenter(results[0].geometry.location);}});}

Find Place from Phone Number

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

• phoneNumber (required) A phone number, inE.164 format.
• fields (required) One or morefields specifying the types of Place data to return.
• locationBias (optional) Coordinates defining the area to search. This can be one of the following:
  • A set of lat/lng coordinates specified asLatLngLiteral orLatLng object
  • Rectangular bounds (four lat/lng points, or aLatLngBounds object)
  • Radius (in meters) centered on a lat/lng

You must also pass a callback method tofindPlaceFromPhoneNumber(),to handle the results object andgoogle.maps.places.PlacesServiceStatusresponse.

Fields (Find Place methods)

The Places fieldsopening_hours.open_now andutc_offset in the Places SDK for iOS are deprecated as of November 20, 2019, and will be turned off on February 20, 2021.Learn more.

Use thefields 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 toPlace Search results, and are dividedinto three billing categories: Basic, Contact, and Atmosphere. Basic fields arebilled at base rate, and incur no additional charges. Contact and Atmospherefields are billed at a higher rate. See thepricing sheetfor more information. Attributions (html_attributions) are alwaysreturned with every call, regardless of whether the field has beenrequested.

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

Atmosphere

ThefindPlaceFromQuery() andfindPlaceFromPhoneNumber() methods each take the same set offields, and can return the same fields in their respective responses.

Set location bias (Find Place methods)

Use thelocationBias parameter to make Find Place favor resultsin a particular area. You can setlocationBias in the followingways:

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 aLatLngBounds.

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:

• aLatLngBounds.
• a circular area defined as the combination of thelocation property — specifying the center of the circle as aLatLng object — and a radius, measured in meters.

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

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

This method takes a request with the following fields:

• Either of:
  • bounds, which must be agoogle.maps.LatLngBounds object defining the rectangular search area. The maximum supported diagonal distance for the bounds area is approximately 100,000 meters.
  • alocation and aradius; the former takes agoogle.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 whenrankBy is set to DISTANCE, you must specify alocation but you cannot specify aradius orbounds.
• 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 andmaxPriceLevel (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 tokeyword. Values in this field are combined with values in thekeyword 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 don't specify opening hours in the Google Places database won't be returned if you include this parameter in your query. SettingopenNow tofalse 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. Whengoogle.maps.places.RankBy.PROMINENCE is specified, theradius parameter is required.
  • google.maps.places.RankBy.DISTANCE. This option sorts results in ascending order by their distance from the specifiedlocation (required). Note that you cannot specify a custombounds and/orradius if you specifyRankBy.DISTANCE. When you specifyRankBy.DISTANCE, one or more ofkeyword,name, ortype 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 thelist of supported types.

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

varmap;varservice;varinfowindow;functioninitialize(){varpyrmont=newgoogle.maps.LatLng(-33.8665433,151.1956316);map=newgoogle.maps.Map(document.getElementById('map'),{center:pyrmont,zoom:15});varrequest={location:pyrmont,radius:500,type:'restaurant'};service=newgoogle.maps.places.PlacesService(map);service.nearbySearch(request,callback);}functioncallback(results,status){if(status==google.maps.places.PlacesServiceStatus.OK){for(vari=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'stextSearch() method.

service=newgoogle.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 thetype 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 don't specify opening hours in the Google Places database won't be returned if you include this parameter in your query. SettingopenNow tofalse has no effect.
  • minPriceLevel andmaxPriceLevel — 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 agoogle.maps.LatLngBounds object defining the rectangular search area. The maximum supported diagonal distance for the bounds area is approximately 100,000 meters.
    • alocation and aradius — You may bias results to a specified circle by passing alocation and aradius 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 agoogle.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 thelist of supported types.

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

varmap;varservice;varinfowindow;functioninitialize(){varpyrmont=newgoogle.maps.LatLng(-33.8665433,151.1956316);map=newgoogle.maps.Map(document.getElementById('map'),{center:pyrmont,zoom:15});varrequest={location:pyrmont,radius:500,query:'restaurant'};service=newgoogle.maps.places.PlacesService(map);service.textSearch(request,callback);}functioncallback(results,status){if(status==google.maps.places.PlacesServiceStatus.OK){for(vari=0;i<results.length;i++){varplace=results[i];createMarker(results[i]);}}}

Search Responses

Status Codes

ThePlacesServiceStatus 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 couldn't 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

ThefindPlace(),nearbySearch() andtextSearch() functions return an array ofPlaceResult objects.

EachPlaceResult 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. Theformatted_address property is only returned for aText 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 moreaddress 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 (valuetrue). Don't usepermanently_closed. Instead, usebusiness_status to get the operational status of businesses.
• plus_code (seeOpen Location Code andplus 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 don't 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). Don't 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. AllPlaceResult 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, useutc_offset_minutes instead).
• place_id is a textual identifier that uniquely identifies a place. To retrieve information about the place, pass this identifier in thePlace Details request. Learn more about how toreference 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 ofsupported 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 avicinity value of5/48 Pirrama Road, Pyrmont.

Access 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 using thePlaceSearchPagination object. In order to access additional pages you must capture thePlaceSearchPagination object using a callback function. ThePlaceSearchPagination 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, callnextPage. 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 thePlaceSearchPagination 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">functioninitMap():void{// Create the map.constpyrmont={lat:-33.866,lng:151.196};constmap=newgoogle.maps.Map(document.getElementById("map")asHTMLElement,{center:pyrmont,zoom:17,mapId:"8d193001f940fde3",}asgoogle.maps.MapOptions);// Create the places service.constservice=newgoogle.maps.places.PlacesService(map);letgetNextPage:()=>void|false;constmoreButton=document.getElementById("more")asHTMLButtonElement;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 callpagination.nextPage();};}});}functionaddPlaces(places:google.maps.places.PlaceResult[],map:google.maps.Map){constplacesList=document.getElementById("places")asHTMLElement;for(constplaceofplaces){if(place.geometry &&place.geometry.location){constimage={url:place.icon!,size:newgoogle.maps.Size(71,71),origin:newgoogle.maps.Point(0,0),anchor:newgoogle.maps.Point(17,34),scaledSize:newgoogle.maps.Size(25,25),};newgoogle.maps.Marker({map,icon:image,title:place.name!,position:place.geometry.location,});constli=document.createElement("li");li.textContent=place.name!;placesList.appendChild(li);li.addEventListener("click",()=>{map.setCenter(place.geometry!.location!);});}}}declareglobal{interfaceWindow{initMap:()=>void;}}window.initMap=initMap;
index.ts

// 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">functioninitMap(){// Create the map.constpyrmont={lat:-33.866,lng:151.196};constmap=newgoogle.maps.Map(document.getElementById("map"),{center:pyrmont,zoom:17,mapId:"8d193001f940fde3",});// Create the places service.constservice=newgoogle.maps.places.PlacesService(map);letgetNextPage;constmoreButton=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 callpagination.nextPage();};}},);}functionaddPlaces(places,map){constplacesList=document.getElementById("places");for(constplaceofplaces){if(place.geometry &&place.geometry.location){constimage={url:place.icon,size:newgoogle.maps.Size(71,71),origin:newgoogle.maps.Point(0,0),anchor:newgoogle.maps.Point(17,34),scaledSize:newgoogle.maps.Size(25,25),};newgoogle.maps.Marker({map,icon:image,title:place.name,position:place.geometry.location,});constli=document.createElement("li");li.textContent=place.name;placesList.appendChild(li);li.addEventListener("click",()=>{map.setCenter(place.geometry.location);});}}}window.initMap=initMap;
index.js

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=newgoogle.maps.places.PlacesService(map);service.getDetails(request,callback);

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

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

varrequest={placeId:'ChIJN1t_tDeuEmsRUsoyG83frY4',fields:['name','rating','formatted_phone_number','geometry']};service=newgoogle.maps.places.PlacesService(map);service.getDetails(request,callback);functioncallback(place,status){if(status==google.maps.places.PlacesServiceStatus.OK){createMarker(place);}}

View example

Fields (Place details)

The Places fieldsopening_hours.open_now andutc_offset in the Places SDK for iOS are deprecated as of November 20, 2019, and will be turned off on February 20, 2021.Learn more.

Use thefields 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 toPlace Detailsresults, and are divided into three billing categories: Basic, Contact, andAtmosphere. Basic fields are billed at base rate, and incur no additionalcharges. Contact and Atmosphere fields are billed at a higher rate. See thepricing sheetfor more information. Attributions (html_attributions) are alwaysreturned 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 moreinformation about how Place data requests are billed, seeUsage and Billing.

Place Details Responses

Status Codes

ThePlacesServiceStatus 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 couldn't 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 successfulgetDetails() call returns aPlaceResult 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 thetype of the address component. See the list ofsupported 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 along_name of "Alaska" and ashort_name of "AK" using the 2-letter postal abbreviation.

  Note the following facts about theaddress_components[] array:

  • The array of address components may contain more components than theformatted_address.
  • The array does not necessarily include all the political entities that contain an address, apart from those included in theformatted_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 ofaddress_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 moreaddress 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 (valuetrue). Don't usepermanently_closed. Instead, usebusiness_status to get the operational status of businesses.
• plus_code (seeOpen Location Code andplus 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 don't 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). Don't 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, theinternational_phone_number for Google's Sydney, Australia office is+61 2 9374 4000.
• name: The place's name.
• utc_offsetDeprecated in the Places Library, Maps JavaScript API, useutc_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; useopening_hours.isOpen() instead. For how to useisOpen with Place Details, see theHow to get opening hours in the Places API video .) `open_now` 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). Thetime 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 isalways open, theclose section will be missing from the response. Applications can rely on always-open being represented as anopen period containingday with value 0 andtime with value 0000, and noclose.
  • weekday_text is an array of seven strings representing the formatted opening hours for each day of the week. If alanguage 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 thelanguage 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 (valuetrue). Don't usepermanently_closed. Instead, usebusiness_status to get the operational status of businesses.
• photos[]: an array ofPlacePhoto objects. APlacePhoto can be used to obtain a photo with thegetUrl() 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 using aPlace Details request. Learn more about how toreference 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 ofPlaceAspectRating 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. EachPlaceAspectRating 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 andservice.
    • 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'.
  • 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 ofsupported 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 avicinity value of5/48 Pirrama Road, Pyrmont. Thevicinity property is only returned for aNearby 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.

Reference 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 isavailable inPlaceResult of a Place Search or Details request.You can then use this place ID to look upPlaceDetails.

Place IDs areexempt from the caching restrictions stated inSection 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.

varmap;functioninitialize(){// Create a map centered in Pyrmont, Sydney (Australia).map=newgoogle.maps.Map(document.getElementById('map'),{center:{lat:-33.8666,lng:151.1958},zoom:15});// Search for Google's office in Australia.varrequest={location:map.getCenter(),radius:'500',query:'Google Sydney'};varservice=newgoogle.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.functioncallback(results,status){if(status==google.maps.places.PlacesServiceStatus.OK){varmarker=newgoogle.maps.Marker({map:map,place:{placeId:results[0].place_id,location:results[0].geometry.location}});}}google.maps.event.addDomListener(window,'load',initialize);

Place Photos

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

An array ofPlacePhoto objects will be returned as part of thePlaceResult object for anygetDetails(),textSearch() ornearbySearch() request made against aPlacesService.

Note: The number of photos returned varies by request.

• A Nearby Search or a Text Search will return at most onePlacePhoto object.
• A Details request will return up to tenPlacePhoto objects.

You can request the URL for the associated image by calling thePlacePhoto.getUrl() method, and passing a validPhotoOptions object. Use thePhotoOptions object to specify the maximum height and width of the image. If youspecify a value for bothmaxHeight and amaxWidth,the photo service will resize the image to the smaller of the two sizes, whilemaintaining 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.

functioncreatePhotoMarker(place){varphotos=place.photos;if(!photos){return;}varmarker=newgoogle.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 oflocations, including business owners and user contributed photos. In mostcases, these photos can be used without attribution, or will have the requiredattribution included as a part of the image. However, if the returnedphoto element includes a value in thehtml_attributions field, you must include the additionalattribution in your application wherever you display the image.