Get Started Contact sales

    Places Service

    PlacesService class

    google.maps.places . PlacesService class

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

    Access by calling const {PlacesService} = await google.maps.importLibrary("places") .See Libraries in the Maps JavaScript API .

    PlacesService
    PlacesService(attrContainer)
    Parameters:
    Creates a new instance of the PlacesService that 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. The PlaceResult s passed to the callback are subsets of a full PlaceResult . Your app can get a more detailed PlaceResult for each place by calling PlacesService.getDetails and passing the PlaceResult.place_id for 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. The PlaceResult s passed to the callback are subsets of a full PlaceResult . Your app can get a more detailed PlaceResult for each place by calling PlacesService.getDetails and passing the PlaceResult.place_id for the desired place.
    getDetails
    getDetails(request, callback)
    Parameters:
    Return Value:  None
    Retrieves details about the place identified by the given placeId .
    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 a LatLngBounds , or location and radius parameters. The PlaceResult s passed to the callback are subsets of the full PlaceResult . Your app can get a more detailed PlaceResult for each place by sending a Place Details request passing the PlaceResult.place_id for the desired place. The PlaceSearchPagination object 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. Use textSearch when 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. The PlaceSearchPagination object 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 the PlacesService .
    placeId
    Type: string
    The Place ID of the Place for which details are being requested.
    fields optional
    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 see PlaceResult . Nested fields can be specified with dot-paths (for example, "geometry.location" ).
    language optional
    Type: string optional
    A language identifier for the language in which details should be returned. See the list of supported languages .
    region optional
    Type: string optional
    A region code of the user's region. This can affect which photos may be returned, and possibly other things. The region code accepts a ccTLD ("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").
    sessionToken optional
    Type: AutocompleteSessionToken optional
    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 to PlacesService.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 see PlaceResult . 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 be E.164 .
    language optional
    Type: string optional
    A language identifier for the language in which names and addresses should be returned, when possible. See the list of supported languages .
    locationBias optional
    Type: LocationBias optional
    The bias used when searching for Place. The result will be biased towards, but not restricted to, the given LocationBias .

    FindPlaceFromQueryRequest interface

    google.maps.places . FindPlaceFromQueryRequest interface

    A find place from text search request to be sent to PlacesService.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 see PlaceResult . 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.
    language optional
    Type: string optional
    A language identifier for the language in which names and addresses should be returned, when possible. See the list of supported languages .
    locationBias optional
    Type: LocationBias optional
    The bias used when searching for Place. The result will be biased towards, but not restricted to, the given LocationBias .

    PlaceSearchRequest interface

    google.maps.places . PlaceSearchRequest interface

    A Place search query to be sent to the PlacesService .
    bounds optional
    The bounds within which to search for Places. Both location and radius will be ignored if bounds is set.
    keyword optional
    Type: string 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.
    language optional
    Type: string optional
    A language identifier for the language in which names and addresses should be returned, when possible. See the list of supported languages .
    location optional
    Type: LatLng | LatLngLiteral optional
    The location around which to search for Places.
    maxPriceLevel optional
    Type: number optional
    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 to minPrice , if specified.
    minPriceLevel optional
    Type: number optional
    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 to maxPrice , if specified.
    name optional
    Type: string optional
    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
    Type: boolean optional
    Restricts results to only those places that are open right now.
    radius optional
    Type: number optional
    The distance from the given location within which to search for Places, in meters. The maximum allowed value is 50 000.
    rankBy optional
    Type: RankBy optional
    Default: RankBy.PROMINENCE
    Specifies the ranking method to use when returning results. Note that when rankBy is set to DISTANCE , you must specify a location but you cannot specify a radius or bounds .
    type optional
    Type: string optional
    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 given here .

    TextSearchRequest interface

    google.maps.places . TextSearchRequest interface

    A text search request to be sent to the PlacesService .
    bounds optional
    Bounds used to bias results when searching for Places (optional). Both location and radius will be ignored if bounds is set. Results will not be restricted to those inside these bounds; but, results inside it will rank higher.
    language optional
    Type: string optional
    A language identifier for the language in which names and addresses should be returned, when possible. See the list of supported languages .
    location optional
    Type: LatLng | LatLngLiteral optional
    The center of the area used to bias results when searching for Places.
    query optional
    Type: string optional
    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').
    radius optional
    Type: number optional
    The radius of the area used to bias results when searching for Places, in meters.
    region optional
    Type: string optional
    A region code to bias results towards. The region code accepts a ccTLD ("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").
    type optional
    Type: string optional
    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 given here .

    RankBy constants

    google.maps.places . RankBy constants

    Ranking options for a PlaceSearchRequest.

    Access by calling const {RankBy} = await google.maps.importLibrary("places") .See Libraries 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 a Circle the center and radius must be defined.

    LatLng | LatLngLiteral | LatLngAltitude | LatLngAltitudeLiteral | 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 the PlacesService on the completion of its searches. Specify these by value, or by using the constant's name. For example, 'OK' or google.maps.places.PlacesServiceStatus.OK .

    Access by calling const {PlacesServiceStatus} = await google.maps.importLibrary("places") .See Libraries 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 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.

    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. true when there is an additional results page.
    nextPage
    nextPage()
    Parameters:  None
    Return Value: void
    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_components optional
    Type: Array < GeocoderAddressComponent > optional
    The collection of address components for this Place’s location. Only available with PlacesService.getDetails .
    adr_address optional
    Type: string optional
    The representation of the Place’s address in the adr microformat . Only available with PlacesService.getDetails .
    aspects optional
    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_status optional
    Type: BusinessStatus optional
    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_address optional
    Type: string optional
    The Place’s full address.
    formatted_phone_number optional
    Type: string optional
    The Place’s phone number, formatted according to the number's regional convention . Only available with PlacesService.getDetails .
    geometry optional
    Type: PlaceGeometry optional
    The Place’s geometry-related information.
    html_attributions optional
    Type: Array <string> optional
    Attribution text to be displayed for this Place result. Available html_attributions are always returned regardless of what fields have been requested, and must be displayed.
    icon optional
    Type: string optional
    URL to an image resource that can be used to represent this Place’s category.
    icon_background_color optional
    Type: string optional
    Background color for use with a Place's icon. See also PlaceResult.icon_mask_base_uri .
    icon_mask_base_uri optional
    Type: string optional
    A truncated URL to an icon mask. Access different icon types by appending a file extension to the end (i.e. .svg or .png ).
    international_phone_number optional
    Type: string optional
    The Place’s phone number in international format. International format includes the country code, and is prefixed with the plus (+) sign. Only available with PlacesService.getDetails .
    name optional
    Type: string optional
    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 (See http://en.wikipedia.org/wiki/Code_injection ).
    opening_hours optional
    Type: PlaceOpeningHours optional
    Defines when the Place opens or closes.
    permanently_closed optional
    Type: boolean optional
    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.
    photos optional
    Type: Array < PlacePhoto > optional
    Photos of this Place. The collection will contain up to ten PlacePhoto objects.
    place_id optional
    Type: string optional
    A unique identifier for the Place.
    plus_code optional
    Type: PlacePlusCode optional
    Defines Open Location Codes or " plus codes " for the Place.
    price_level optional
    Type: number optional
    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
    rating optional
    Type: number optional
    A rating, between 1.0 to 5.0, based on user reviews of this Place.
    reviews optional
    Type: Array < PlaceReview > optional
    A list of reviews of this Place. Only available with PlacesService.getDetails .
    types optional
    Type: Array <string> optional
    An array of types for this Place (for example, ["political", "locality"] or ["restaurant", "establishment"] ).
    url optional
    Type: string optional
    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 with PlacesService.getDetails .
    user_ratings_total optional
    Type: number optional
    The number of user ratings which contributed to this Place’s PlaceResult.rating .
    utc_offset optional
    Type: number optional
    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 the utc_offset will be 660 . For timezones behind UTC, the offset is negative. For example, the utc_offset is -60 for Cape Verde. Only available with PlacesService.getDetails .
    utc_offset_minutes optional
    Type: number optional
    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 the utc_offset_minutes will be 660 . For timezones behind UTC, the offset is negative. For example, the utc_offset_minutes is -60 for Cape Verde. Only available with PlacesService.getDetails .
    vicinity optional
    Type: string optional
    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 with PlacesService.getDetails .
    website optional
    Type: string optional
    The authoritative website for this Place, such as a business' homepage. Only available with PlacesService.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' or google.maps.places.BusinessStatus.OPERATIONAL ).

    Access by calling const {BusinessStatus} = await google.maps.importLibrary("places") .See Libraries 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.
    location optional
    Type: LatLng optional
    The Place’s position.
    viewport optional
    Type: LatLngBounds optional
    The preferred viewport when displaying this Place on a map. This property will be null if the preferred viewport for the Place is not known. Only available with PlacesService.getDetails .

    PlaceOpeningHours interface

    google.maps.places . PlaceOpeningHours interface

    Defines information about the opening hours of a Place.
    open_now optional
    Type: boolean optional
    Whether the Place is open at the current time.
    periods optional
    Type: Array < PlaceOpeningHoursPeriod > optional
    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 with PlacesService.getDetails .
    weekday_text optional
    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 with PlacesService.getDetails . Other calls may return an empty array.
    isOpen
    isOpen([date])
    Parameters:
    • date :  Date optional
    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 have PlaceResult.utc_offset_minutes or PlaceOpeningHours.periods then undefined is returned ( PlaceOpeningHours.periods is only available via PlacesService.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 is always open, the close section will be missing from the response. Clients can rely on always-open being represented as an open period containing day with value 0 and time with value "0000" , and no close .
    open
    The opening time for the Place.
    close optional
    Type: PlaceOpeningHoursTime optional
    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, 2 means Tuesday.
    hours
    Type: number
    The hours of the PlaceOpeningHoursTime.time as a number, in the range [ 0 , 23 ]. This will be reported in the Place’s time zone.
    minutes
    Type: number
    The minutes of the PlaceOpeningHoursTime.time as 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.
    nextDate optional
    Type: number optional
    The timestamp (as milliseconds since the epoch, suitable for use with new Date() ) representing the next occurrence of this PlaceOpeningHoursTime. It is calculated from the PlaceOpeningHoursTime.day of week, the PlaceOpeningHoursTime.time , and the PlaceResult.utc_offset_minutes . If the PlaceResult.utc_offset_minutes is undefined , then nextDate will be undefined .

    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
    A plus code with a 1/8000th of a degree by 1/8000th of a degree area. For example, "8FVC9G8F+5W" .
    compound_code optional
    Type: string optional
    A plus code with 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.
    maxHeight optional
    Type: number optional
    The maximum height in pixels of the returned image.
    maxWidth optional
    Type: number optional
    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.
    aspects optional
    Type: Array < PlaceAspectRating > optional
    The aspects rated by the review. The ratings on a scale of 0 to 3.
    author_url optional
    Type: string optional
    A URL to the reviewer's profile. This will be undefined when the reviewer's profile is unavailable.
    rating optional
    Type: number optional
    The rating of this review, a number between 1.0 and 5.0 (inclusive).
    Create a Mobile Website
    View Site in Mobile | Classic
    Share by: