Places Service

PlacesService class

google.maps.places.PlacesService class

Contains methods related to searching for places and retrieving details about a place.

Access by callingconst {PlacesService} = await google.maps.importLibrary( "places" ).SeeLibraries in the Maps JavaScript API.

PlacesService
PlacesService(attrContainer)
Parameters:
Creates a new instance of thePlacesServicethat renders attributions in the specified container.
findPlaceFromPhoneNumber
findPlaceFromPhoneNumber(request, callback)
Parameters:
Return Value:None
Retrieves a list of places based on a phone number. In most cases there should be just one item in the result list, however if the request is ambiguous more than one result may be returned. ThePlaceResults passed to the callback are subsets of a fullPlaceResult.Your app can get a more detailedPlaceResultfor each place by callingPlacesService.getDetailsand passing thePlaceResult.place_idfor the desired place.
findPlaceFromQuery
findPlaceFromQuery(request, callback)
Parameters:
Return Value:None
Retrieves a list of places based on a query string. In most cases there should be just one item in the result list, however if the request is ambiguous more than one result may be returned. ThePlaceResults passed to the callback are subsets of a fullPlaceResult.Your app can get a more detailedPlaceResultfor each place by callingPlacesService.getDetailsand passing thePlaceResult.place_idfor the desired place.
getDetails
getDetails(request, callback)
Parameters:
Return Value:None
Retrieves details about the place identified by the givenplaceId.
nearbySearch
nearbySearch(request, callback)
Parameters:
Return Value:None
Retrieves a list of places near a particular location, based on keyword or type. Location must always be specified, either by passing aLatLngBounds,orlocationandradiusparameters. ThePlaceResults passed to the callback are subsets of the fullPlaceResult.Your app can get a more detailedPlaceResultfor each place by sending aPlace Details requestpassing thePlaceResult.place_idfor the desired place. ThePlaceSearchPaginationobject can be used to fetch additional pages of results (null if this is the last page of results or if there is only one page of results).
textSearch
textSearch(request, callback)
Parameters:
Return Value:None
Retrieves a list of places based on a query string (for example, "pizza in New York", or "shoe stores near Ottawa" ). Location parameters are optional; when the location is specified, results are only biased toward nearby results rather than restricted to places inside the area. UsetextSearchwhen you want to search for places using an arbitrary string, and in cases where you may not want to restrict search results to a particular location. ThePlaceSearchPaginationobject can be used to fetch additional pages of results (null if this is the last page of results or if there is only one page of results).

PlaceDetailsRequest interface

google.maps.places.PlaceDetailsRequest interface

A Place details query to be sent to thePlacesService.

placeId
Type:string
The Place ID of the Place for which details are being requested.
fieldsoptional
Type:Array<string>optional
Fields to be included in the details response,which will be billed for.If no fields are specified or['ALL']is passed in, all available fields will be returned and billed for (this is not recommended for production deployments). For a list of fields seePlaceResult.Nested fields can be specified with dot-paths (for example,"geometry.location").
languageoptional
Type:stringoptional
A language identifier for the language in which details should be returned. See thelist of supported languages.
regionoptional
Type:stringoptional
A region code of the user's region. This can affect which photos may be returned, and possibly other things. The region code accepts accTLD ( "top-level domain" )two-character value. Most ccTLD codes are identical to ISO 3166-1 codes, with some notable exceptions. For example, the United Kingdom's ccTLD is "uk" (.co.uk) while its ISO 3166-1 code is "gb" (technically for the entity of "The United Kingdom of Great Britain and Northern Ireland" ).
sessionTokenoptional
Unique reference used to bundle the details request with an autocomplete session.

FindPlaceFromPhoneNumberRequest interface

google.maps.places.FindPlaceFromPhoneNumberRequest interface

A find place from text search request to be sent toPlacesService.findPlaceFromPhoneNumber.

fields
Type:Array<string>
Fields to be included in the response,which will be billed for.If['ALL']is passed in, all available fields will be returned and billed for (this is not recommended for production deployments). For a list of fields seePlaceResult.Nested fields can be specified with dot-paths (for example,"geometry.location").
phoneNumber
Type:string
The phone number of the place to look up. Format must beE.164.
languageoptional
Type:stringoptional
A language identifier for the language in which names and addresses should be returned, when possible. See thelist of supported languages.
locationBiasoptional
Type:LocationBiasoptional
The bias used when searching for Place. The result will be biased towards, but not restricted to, the givenLocationBias.

FindPlaceFromQueryRequest interface

google.maps.places.FindPlaceFromQueryRequest interface

A find place from text search request to be sent toPlacesService.findPlaceFromQuery.

fields
Type:Array<string>
Fields to be included in the response,which will be billed for.If['ALL']is passed in, all available fields will be returned and billed for (this is not recommended for production deployments). For a list of fields seePlaceResult.Nested fields can be specified with dot-paths (for example,"geometry.location").
query
Type:string
The request's query. For example, the name or address of a place.
languageoptional
Type:stringoptional
A language identifier for the language in which names and addresses should be returned, when possible. See thelist of supported languages.
locationBiasoptional
Type:LocationBiasoptional
The bias used when searching for Place. The result will be biased towards, but not restricted to, the givenLocationBias.

PlaceSearchRequest interface

google.maps.places.PlaceSearchRequest interface

A Place search query to be sent to thePlacesService.

boundsoptional
The bounds within which to search for Places. Bothlocationandradiuswill be ignored ifboundsis set.
keywordoptional
Type:stringoptional
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.
languageoptional
Type:stringoptional
A language identifier for the language in which names and addresses should be returned, when possible. See thelist of supported languages.
locationoptional
Type:LatLng|LatLngLiteraloptional
The location around which to search for Places.
maxPriceLeveloptional
Type:numberoptional
Restricts results to only those places at the specified price level or lower. Valid values are in the range from 0 (most affordable) to 4 (most expensive), inclusive. Must be greater than or equal tominPrice,if specified.
minPriceLeveloptional
Type:numberoptional
Restricts results to only those places at the specified price level or higher. Valid values are in the range from 0 (most affordable) to 4 (most expensive), inclusive. Must be less than or equal tomaxPrice,if specified.
nameoptional
Type:stringoptional
Equivalent tokeyword.Values in this field are combined with values in thekeywordfield and passed as part of the same search string.
openNowoptional
Type:booleanoptional
Restricts results to only those places that are open right now.
radiusoptional
Type:numberoptional
The distance from the given location within which to search for Places, in meters. The maximum allowed value is 50 000.
rankByoptional
Type:RankByoptional
Specifies the ranking method to use when returning results. Note that whenrankByis set toDISTANCE,you must specify alocationbut you cannot specify aradiusorbounds.
typeoptional
Type:stringoptional
Searches for places of the given type. The type is translated to the local language of the request's target location and used as a query string. If a query is also provided, it is concatenated to the localized type string. Results of a different type are dropped from the response. Use this field to perform language and region independent categorical searches. Valid types are givenhere.

TextSearchRequest interface

google.maps.places.TextSearchRequest interface

A text search request to be sent to thePlacesService.

boundsoptional
Bounds used to bias results when searching for Places (optional). Bothlocationandradiuswill be ignored ifboundsis set. Results will not be restricted to those inside these bounds; but, results inside it will rank higher.
languageoptional
Type:stringoptional
A language identifier for the language in which names and addresses should be returned, when possible. See thelist of supported languages.
locationoptional
Type:LatLng|LatLngLiteraloptional
The center of the area used to bias results when searching for Places.
queryoptional
Type:stringoptional
The request's query term. For example, the name of a place ('Eiffel Tower'), a category followed by the name of a location ('pizza in New York'), or the name of a place followed by a location disambiguator ('Starbucks in Sydney').
radiusoptional
Type:numberoptional
The radius of the area used to bias results when searching for Places, in meters.
regionoptional
Type:stringoptional
A region code to bias results towards. The region code accepts accTLD ( "top-level domain" )two-character value. Most ccTLD codes are identical to ISO 3166-1 codes, with some notable exceptions. For example, the United Kingdom's ccTLD is "uk" (.co.uk) while its ISO 3166-1 code is "gb" (technically for the entity of "The United Kingdom of Great Britain and Northern Ireland" ).
typeoptional
Type:stringoptional
Searches for places of the given type. The type is translated to the local language of the request's target location and used as a query string. If a query is also provided, it is concatenated to the localized type string. Results of a different type are dropped from the response. Use this field to perform language and region independent categorical searches. Valid types are givenhere.

RankBy constants

google.maps.places.RankBy constants

Ranking options for a PlaceSearchRequest.

Access by callingconst {RankBy} = await google.maps.importLibrary( "places" ).SeeLibraries in the Maps JavaScript API.

DISTANCE Ranks place results by distance from the location.
PROMINENCE Ranks place results by their prominence.

LocationBias typedef

google.maps.places.LocationBias typedef

A LocationBias represents a soft boundary or hint to use when searching for Places. Results may come from outside the specified area. To use the current user's IP address as a bias, the string"IP_BIAS"can be specified. Note: if using aCirclethe center and radius must be defined.

LatLng|LatLngLiteral|LatLngBounds|LatLngBoundsLiteral|Circle|CircleLiteral|string

LocationRestriction typedef

google.maps.places.LocationRestriction typedef

A LocationRestriction represents a strict boundary to use when searching for Places.

LatLngBounds|LatLngBoundsLiteral

PlacesServiceStatus constants

google.maps.places.PlacesServiceStatus constants

The status returned by thePlacesServiceon the completion of its searches. Specify these by value, or by using the constant's name. For example,'OK'orgoogle.maps.places.PlacesServiceStatus.OK.

Access by callingconst {PlacesServiceStatus} = await google.maps.importLibrary( "places" ).SeeLibraries in the Maps JavaScript API.

INVALID_REQUEST This request was invalid.
NOT_FOUND The place referenced was not found.
OK The response contains a valid result.
OVER_QUERY_LIMIT The application has gone over its request quota.
REQUEST_DENIED The application is not allowed to use thePlacesService.
UNKNOWN_ERROR ThePlacesServicerequest 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.

PlaceSearchPagination interface

google.maps.places.PlaceSearchPagination interface

An object used to fetch additional pages of Places results.

hasNextPage
Type:boolean
Indicates if further results are available.truewhen there is an additional results page.
nextPage
nextPage()
Parameters:None
Return Value:None
Fetches the next page of results. Uses the same callback function that was provided to the first search request.

PlaceResult interface

google.maps.places.PlaceResult interface

Defines information about a Place.

address_componentsoptional
The collection of address components for this Place’s location. Only available withPlacesService.getDetails.
adr_addressoptional
Type:stringoptional
The representation of the Place’s address in theadr microformat.Only available withPlacesService.getDetails.
aspectsoptional
Type:Array<PlaceAspectRating>optional
The rated aspects of this Place, based on Google and Zagat user reviews. The ratings are on a scale of 0 to 30.
business_statusoptional
Type:BusinessStatusoptional
A flag indicating the operational status of the Place, if it is a business (indicates whether the place is operational, or closed either temporarily or permanently). If no data is available, the flag is not present in search or details responses.
formatted_addressoptional
Type:stringoptional
The Place’s full address.
formatted_phone_numberoptional
Type:stringoptional
The Place’s phone number, formatted according to thenumber's regional convention.Only available withPlacesService.getDetails.
geometryoptional
Type:PlaceGeometryoptional
The Place’s geometry-related information.
html_attributionsoptional
Type:Array<string>optional
Attribution text to be displayed for this Place result. Availablehtml_attributionsare always returned regardless of whatfieldshave been requested, and must be displayed.
iconoptional
Type:stringoptional
URL to an image resource that can be used to represent this Place’s category.
icon_background_coloroptional
Type:stringoptional
Background color for use with a Place's icon. See alsoPlaceResult.icon_mask_base_uri.
icon_mask_base_urioptional
Type:stringoptional
A truncated URL to an icon mask. Access different icon types by appending a file extension to the end (i.e..svgor.png).
international_phone_numberoptional
Type:stringoptional
The Place’s phone number in international format. International format includes the country code, and is prefixed with the plus (+) sign. Only available withPlacesService.getDetails.
nameoptional
Type:stringoptional
The Place’s name. Note: In the case of user entered Places, this is the raw text, as typed by the user. Please exercise caution when using this data, as malicious users may try to use it as a vector for code injection attacks (Seehttp://en.wikipedia.org/wiki/Code_injection).
opening_hoursoptional
Type:PlaceOpeningHoursoptional
Defines when the Place opens or closes.
permanently_closedoptional
Type:booleanoptional
A flag indicating whether the Place is closed, either permanently or temporarily. If the place is operational, or if no data is available, the flag is absent from the response.
photosoptional
Type:Array<PlacePhoto>optional
Photos of this Place. The collection will contain up to tenPlacePhotoobjects.
place_idoptional
Type:stringoptional
A unique identifier for the Place.
plus_codeoptional
Type:PlacePlusCodeoptional
Defines Open Location Codes or "plus codes"for the Place.
price_leveloptional
Type:numberoptional
The price level of the Place, on a scale of 0 to 4. Price levels are interpreted as follows:
  • 0:Free
  • 1:Inexpensive
  • 2:Moderate
  • 3:Expensive
  • 4:Very Expensive
ratingoptional
Type:numberoptional
A rating, between 1.0 to 5.0, based on user reviews of this Place.
reviewsoptional
Type:Array<PlaceReview>optional
A list of reviews of this Place. Only available withPlacesService.getDetails.
typesoptional
Type:Array<string>optional
An array oftypes for this Place(for example,[ "political", "locality" ]or[ "restaurant", "establishment" ]).
urloptional
Type:stringoptional
URL of the official Google page for this place. This is the Google-owned page that contains the best available information about the Place. Only available withPlacesService.getDetails.
user_ratings_totaloptional
Type:numberoptional
The number of user ratings which contributed to this Place’sPlaceResult.rating.
utc_offsetoptional
Type:numberoptional
The offset from UTC of the Place’s current timezone, in minutes. For example, Sydney, Australia in daylight savings is 11 hours ahead of UTC, so theutc_offsetwill be660.For timezones behind UTC, the offset is negative. For example, theutc_offsetis-60for Cape Verde. Only available withPlacesService.getDetails.
utc_offset_minutesoptional
Type:numberoptional
The offset from UTC of the Place’s current timezone, in minutes. For example, Sydney, Australia in daylight savings is 11 hours ahead of UTC, so theutc_offset_minuteswill be660.For timezones behind UTC, the offset is negative. For example, theutc_offset_minutesis-60for Cape Verde. Only available withPlacesService.getDetails.
vicinityoptional
Type:stringoptional
The 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"48 Pirrama Road, Pyrmont".Only available withPlacesService.getDetails.
websiteoptional
Type:stringoptional
The authoritative website for this Place, such as a business' homepage. Only available withPlacesService.getDetails.

PlaceAspectRating interface

google.maps.places.PlaceAspectRating interface

Defines information about an aspect of the place that users have reviewed.

rating
Type:number
The rating of this aspect. For individual reviews this is an integer from 0 to 3. For aggregated ratings of a place this is an integer from 0 to 30.
type
Type:string
The aspect type. For example,"food","decor","service",or"overall".

BusinessStatus constants

google.maps.places.BusinessStatus constants

The operational status of the Place, if it is a business, returned in a PlaceResult (indicates whether the place is operational, or closed either temporarily or permanently). Specify these by value, or the constant's name (example:'OPERATIONAL'orgoogle.maps.places.BusinessStatus.OPERATIONAL).

Access by callingconst {BusinessStatus} = await google.maps.importLibrary( "places" ).SeeLibraries in the Maps JavaScript API.

CLOSED_PERMANENTLY The business is closed permanently.
CLOSED_TEMPORARILY The business is closed temporarily.
OPERATIONAL The business is operating normally.

PlaceGeometry interface

google.maps.places.PlaceGeometry interface

Defines information about the geometry of a Place.

locationoptional
Type:LatLngoptional
The Place’s position.
viewportoptional
Type:LatLngBoundsoptional
The preferred viewport when displaying this Place on a map. This property will benullif the preferred viewport for the Place is not known. Only available withPlacesService.getDetails.

PlaceOpeningHours interface

google.maps.places.PlaceOpeningHours interface

Defines information about the opening hours of a Place.

open_nowoptional
Type:booleanoptional
Whether the Place is open at the current time.
periodsoptional
Opening periods covering for each day of the week, starting from Sunday, in chronological order. Days in which the Place is not open are not included. Only available withPlacesService.getDetails.
weekday_textoptional
Type:Array<string>optional
An array of seven strings representing the formatted opening hours for each day of the week. The Places Service will format and localize the opening hours appropriately for the current language. The ordering of the elements in this array depends on the language. Some languages start the week on Monday while others start on Sunday. Only available withPlacesService.getDetails.Other calls may return an empty array.
isOpen
isOpen([date])
Parameters:
Return Value:boolean|undefined
Check whether the place is open now (when no date is passed), or at the given date. If this place does not havePlaceResult.utc_offset_minutesorPlaceOpeningHours.periodsthenundefinedis returned (PlaceOpeningHours.periodsis only available viaPlacesService.getDetails). This method does not take exceptional hours, such as holiday hours, into consideration.

PlaceOpeningHoursPeriod interface

google.maps.places.PlaceOpeningHoursPeriod interface

Defines structured information about the opening hours of a Place.Note:If a Place isalways open,theclosesection will be missing from the response. Clients can rely on always-open being represented as anopenperiod containingdaywith value0andtimewith value"0000",and noclose.

open
The opening time for the Place.
closeoptional
The closing time for the Place.

PlaceOpeningHoursTime interface

google.maps.places.PlaceOpeningHoursTime interface

Defines when a Place opens or closes.

day
Type:number
The days of the week, as a number in the range [0,6], starting on Sunday. For example,2means Tuesday.
hours
Type:number
The hours of thePlaceOpeningHoursTime.timeas a number, in the range [0,23]. This will be reported in the Place’s time zone.
minutes
Type:number
The minutes of thePlaceOpeningHoursTime.timeas a number, in the range [0,59]. This will be reported in the Place’s time zone.
time
Type:string
The time of day in 24-hour "hhmm" format. Values are in the range ["0000","2359"]. The time will be reported in the Place’s time zone.
nextDateoptional
Type:numberoptional
The timestamp (as milliseconds since the epoch, suitable for use withnew Date()) representing the next occurrence of this PlaceOpeningHoursTime. It is calculated from thePlaceOpeningHoursTime.dayof week, thePlaceOpeningHoursTime.time,and thePlaceResult.utc_offset_minutes.If thePlaceResult.utc_offset_minutesisundefined,thennextDatewill beundefined.

PlacePlusCode interface

google.maps.places.PlacePlusCode interface

Defines Open Location Codes or "plus codes"for a Place. 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).

global_code
Type:string
Aplus codewith a 1/8000th of a degree by 1/8000th of a degree area. For example,"8FVC9G8F+5W".
compound_codeoptional
Type:stringoptional
Aplus codewith a 1/8000th of a degree by 1/8000th of a degree area where the first four characters (the area code) are dropped and replaced with a locality description. For example,"9G8F+5W Zurich, Switzerland".If no suitable locality that can be found to shorten the code then this field is omitted.

PlacePhoto interface

google.maps.places.PlacePhoto interface

Represents a photo element of a Place.

height
Type:number
The height of the photo in pixels.
html_attributions
Type:Array<string>
Attribution text to be displayed for this photo.
width
Type:number
The width of the photo in pixels.
getUrl
getUrl([opts])
Parameters:
Return Value:string
Returns the image URL corresponding to the specified options.

PhotoOptions interface

google.maps.places.PhotoOptions interface

Defines photo-requesting options.

maxHeightoptional
Type:numberoptional
The maximum height in pixels of the returned image.
maxWidthoptional
Type:numberoptional
The maximum width in pixels of the returned image.

PlaceReview interface

google.maps.places.PlaceReview interface

Represents a single review of a place.

author_name
Type:string
The name of the reviewer.
language
Type:string
An IETF language code indicating the language in which this review is written. Note that this code includes only the main language tag without any secondary tag indicating country or region. For example, all the English reviews are tagged as'en'rather than 'en-AU' or 'en-UK'.
profile_photo_url
Type:string
A URL to the reviwer's profile image.
relative_time_description
Type:string
A string of formatted recent time, expressing the review time relative to the current time in a form appropriate for the language and country. For example"a month ago".
text
Type:string
The text of a review.
time
Type:number
Timestamp for the review, expressed in seconds since epoch.
aspectsoptional
Type:Array<PlaceAspectRating>optional
The aspects rated by the review. The ratings on a scale of 0 to 3.
author_urloptional
Type:stringoptional
A URL to the reviewer's profile. This will beundefinedwhen the reviewer's profile is unavailable.
ratingoptional
Type:numberoptional
The rating of this review, a number between 1.0 and 5.0 (inclusive).