Introducing Places UI Kit :A ready-to-use, low-cost component library that lets you bring the familiar Google Maps UI for Places to any map of your choice. Try it out, and share your input to help shape the future of GMP!

Places Widgets

PlaceAutocompleteElement class

google.maps.places . PlaceAutocompleteElement class

PlaceAutocompleteElement is an HTMLElement subclass which provides a UI component for the Places Autocomplete API.

Custom element: <gmp-place-autocomplete included-primary-types="type1 type2 type3..." included-region-codes="c1 c2 c3..." name="string" origin="lat,lng|lat,lng,altitude" requested-language="string" requested-region="string" unit-system="metric|imperial" types="type1 type2 type3..."></gmp-place-autocomplete>

This class extends HTMLElement .

This class implements PlaceAutocompleteElementOptions .

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

Constructor

 PlaceAutocompleteElement

PlaceAutocompleteElement(options)

Parameters:

options : PlaceAutocompleteElementOptions

Properties

 includedPrimaryTypes

Type:

 Array 
<string> optional

Included primary Place type (for example, "restaurant" or "gas_station").

A Place is only returned if its primary type is included in this list. Up to 5 values can be specified. If no types are specified, all Place types are returned.

HTML attribute:

<gmp-place-autocomplete included-primary-types="type1 type2 type3..."></gmp-place-autocomplete>

 includedRegionCodes

Type:

 Array 
<string> optional

Only include results in the specified regions, specified as up to 15 CLDR two-character region codes. An empty set will not restrict the results. If both locationRestriction and includedRegionCodes are set, the results will be located in the area of intersection.

HTML attribute:

<gmp-place-autocomplete included-region-codes="c1 c2 c3..."></gmp-place-autocomplete>

 locationBias

Type:

 LocationBias 
 optional

A soft boundary or hint to use when searching for places.

 locationRestriction

Type:

 LocationRestriction 
 optional

Bounds to constrain search results.

 name

Type:

string optional

The name to be used for the input element. See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#name for details. Follows the same behavior as the name attribute for inputs. Note that this is the name that will be used when a form is submitted. See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form for details.

HTML attribute:

<gmp-place-autocomplete name="string"></gmp-place-autocomplete>

 origin

Type:

 LatLng 
| LatLngLiteral 
| LatLngAltitude 
| LatLngAltitudeLiteral 
 optional

The origin from which to calculate distance. If not specified, distance is not calculated. The altitude, if given, is not used in the calculation.

HTML attribute:

<gmp-place-autocomplete origin="lat,lng|lat,lng,altitude"></gmp-place-autocomplete>

 requestedLanguage

Type:

string optional

A language identifier for the language in which the results should be returned, if possible. Results in the selected language may be given a higher ranking, but suggestions are not restricted to this language. See the list of supported languages .

HTML attribute:

<gmp-place-autocomplete requested-language="string"></gmp-place-autocomplete>

 requestedRegion

Type:

string optional

A region code which is used for result formatting and for result filtering. It does not restrict the suggestions to this country. 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").

HTML attribute:

<gmp-place-autocomplete requested-region="string"></gmp-place-autocomplete>

 unitSystem

Type:

 UnitSystem 
 optional

The unit system used to display distances. If not specified, the unit system is determined by requestedRegion.

HTML attribute:

<gmp-place-autocomplete unit-system="metric|imperial"></gmp-place-autocomplete>

~~componentRestrictions~~

Type:

 ComponentRestrictions 
 optional

The component restrictions. Component restrictions are used to restrict predictions to only those within the parent component. For example, the country.

~~types~~

Type:

 Array 
<string> optional

The types of predictions to be returned. For supported types, see the developer's guide . If no types are specified, all types will be returned.

HTML attribute:

<gmp-place-autocomplete types="type1 type2 type3..."></gmp-place-autocomplete>

Parts
`prediction-item`	An item in the drop down of predictions that represents a single prediction.
`prediction-item-icon`	The icon displayed to the left of each item in the list of predictions.
`prediction-item-main-text`	A part of prediction-item that is the main text of the prediction. For geographic locations, this contains a place name, like 'Sydney', or a street name and number, like '10 King Street'. By default, the prediction-item-main-text is colored black. If there is any additional text in the prediction-item, it is outside prediction-item-main-text and inherits its styling from prediction-item. It is colored gray by default. The additional text is typically an address.
`prediction-item-match`	The part of the returned prediction that matches the user’s input. By default, this matched text is highlighted in bold text. Note that the matched text may be anywhere within prediction-item. It is not necessarily part of prediction-item-main-text.
`prediction-item-selected`	The item when the user navigates to it via the keyboard. Note: Selected items will be affected by both this part styles and also the prediction-item part styles.
`prediction-list`	The visual element containing the list of predictions returned by the Place Autocomplete service. This list appears as a dropdown list below the PlaceAutocompleteElement.

Methods

 addEventListener

addEventListener(type, listener[, options])

Parameters:

type : string A case-sensitive string representing the event type to listen for.
listener : EventListener | EventListenerObject The object that receives a notification. This must be a function or an object with the handleEvent method
options : boolean| AddEventListenerOptions optional See options . Custom events only support capture and passive .

Return Value: void

Sets up a function that will be called whenever the specified event is delivered to the target. See addEventListener .

 removeEventListener

removeEventListener(type, listener[, options])

Parameters:

type : string A string which specifies the type of event for which to remove an event listener.
listener : EventListener | EventListenerObject The event listener of the event handler to remove from the event target.
options : boolean| EventListenerOptions optional See options .

Return Value: void

Removes an event listener previously registered with addEventListener from the target. See removeEventListener .

Events

 gmp-error

function(errorEvent)

Arguments:

errorEvent : Event

This event is fired when a request to the backend was denied (e.g. incorrect API key). This event does not bubble.

 gmp-select

function(placePredictionSelectEvent)

Arguments:

placePredictionSelectEvent : PlacePredictionSelectEvent

This event is fired when a user selects a place prediction. Contains a PlacePrediction object which can be converted to a Place object.

~~gmp-placeselect~~

function(placeAutocompletePlaceSelectEvent)

Arguments:

placeAutocompletePlaceSelectEvent : PlaceAutocompletePlaceSelectEvent

This event is fired when a user selects a place prediction. Contains a Place object.

PlaceAutocompleteElementOptions interface

google.maps.places . PlaceAutocompleteElementOptions interface

Options for constructing a PlaceAutocompleteElement. For the description of each property, refer to the property of the same name in the PlaceAutocompleteElement class.

Properties
~~`componentRestrictions`~~ optional	Deprecated: This property will continue to function in the beta channel, but will not be made available in alpha or at release. For migration purposes, specify both this property and `includedRegionCodes` . Notice: Available only in the v=beta channel . Type: `ComponentRestrictions optional`
`includedPrimaryTypes optional`	Notice: Available only in the v=alpha channel . Type: `Array <string> optional`
`includedRegionCodes optional`	Notice: Available only in the v=alpha channel . Type: `Array <string> optional`
`locationBias optional`	Type: `LocationBias optional`
`locationRestriction optional`	Type: `LocationRestriction optional`
`name optional`	Type: `string optional`
`origin optional`	Notice: Available only in the v=alpha channel . Type: `LatLng \| LatLngLiteral \| LatLngAltitude \| LatLngAltitudeLiteral optional`
`requestedLanguage optional`	Type: `string optional`
~~`types`~~ optional	Deprecated: This property will continue to function in the beta channel, but will not be made available in alpha or at release. For migration purposes, specify both this property and `includedPrimaryTypes` . Notice: Available only in the v=beta channel . Type: `Array <string> optional`
`unitSystem optional`	Notice: Available only in the v=alpha channel . Type: `UnitSystem optional`

PlaceAutocompletePlaceSelectEvent class

google.maps.places . PlaceAutocompletePlaceSelectEvent class

This event is created after the user selects a place with the Place Autocomplete Element. Access the selection with event.place .

This class extends Event .

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

Properties
`place`	Notice: Available only in the v=beta channel . Type: `Place`

PlacePredictionSelectEvent class

google.maps.places . PlacePredictionSelectEvent class

This event is created after the user selects a prediction item with the PlaceAutocompleteElement. Access the selection with event.placePrediction .

This class extends Event .

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

Properties
`placePrediction`	Type: `PlacePrediction`

PlaceAutocompleteRequestErrorEvent class

google.maps.places . PlaceAutocompleteRequestErrorEvent class

This event is emitted by the PlaceAutocompleteElement when there is an issue with the network request.

This class extends Event .

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

PlaceDetailsElement class

google.maps.places . PlaceDetailsElement class

An HTML element that displays details for a place. Use the configureFromPlace() or configureFromLocation() methods to specify the content to be rendered. To use the Place Details Element, enable the Places UI Kit API for your project in the Google Cloud console.

Custom element: <gmp-place-details size="small"></gmp-place-details>

This class extends HTMLElement .

This class implements PlaceDetailsElementOptions .

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

Constructor

 PlaceDetailsElement

PlaceDetailsElement([options])

Parameters:

options : PlaceDetailsElementOptions optional

Properties

 place

Type:

 Place 
 optional

Read only. Place object containing the ID, location, and viewport of the currently rendered place.

 size

Type:

 PlaceDetailsSize 
 optional

The size variant of the PlaceDetailsElement. By default, the element will display PlaceDetailsSize.X_LARGE .

HTML attribute:

<gmp-place-details size="small"></gmp-place-details>
<gmp-place-details size="medium"></gmp-place-details>
<gmp-place-details size="large"></gmp-place-details>
<gmp-place-details size="x-large"></gmp-place-details>

Methods

 addEventListener

addEventListener(type, listener[, options])

Parameters:

type : string A case-sensitive string representing the event type to listen for.
listener : EventListener | EventListenerObject The object that receives a notification. This must be a function or an object with the handleEvent method
options : boolean| AddEventListenerOptions optional See options . Custom events only support capture and passive .

Return Value: void

Sets up a function that will be called whenever the specified event is delivered to the target. See addEventListener .

 configureFromLocation

configureFromLocation(location)

Parameters:

location : LatLng | LatLngLiteral The location to render place details for.

Return Value:

 Promise 
<void>

A promise that resolves once place data is loaded and rendered.

Configures the widget from a LatLng using reverse geocoding.

 configureFromPlace

configureFromPlace(place)

Parameters:

place : Place |{id:string} The place to render details for.

Return Value:

 Promise 
<void>

A promise that resolves once place data is loaded and rendered.

Configures the widget from a Place object or Place ID.

 removeEventListener

removeEventListener(type, listener[, options])

Parameters:

type : string A string which specifies the type of event for which to remove an event listener.
listener : EventListener | EventListenerObject The event listener of the event handler to remove from the event target.
options : boolean| EventListenerOptions optional See options .

Return Value: void

Removes an event listener previously registered with addEventListener from the target. See removeEventListener .

Events

 gmp-load

function(event)

Arguments:

event : Event

This event is fired when the element loads and renders its content. This event does not bubble.

 gmp-requesterror

function(event)

Arguments:

event : Event

This event is fired when a request to the backend was denied (e.g. incorrect API key). This event does not bubble.

PlaceDetailsElementOptions interface

google.maps.places . PlaceDetailsElementOptions interface

Options for PlaceDetailsElement .

Properties
`size optional`	Type: `PlaceDetailsSize optional` See `PlaceDetailsElement.size`

PlaceDetailsSize constants

google.maps.places . PlaceDetailsSize constants

Size variants for PlaceDetailsElement .

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

Constants
`LARGE`	Large variant including a large image, basic information, and contact information.
`MEDIUM`	Medium variant including a large image and basic information.
`SMALL`	Small variant including a small image and basic information.
`X_LARGE`	Extra large variant including a photo collage, reviews, and comprehensive place information.

PlaceListElement class

google.maps.places . PlaceListElement class

An HTML element that displays the results of a place search in a list. Use the configureFromSearchByTextRequest() or configureFromSearchNearbyRequest() methods to specify the request to render results for. To use the Place List Element, enable the Places UI Kit API for your project in the Google Cloud console.

Custom element: <gmp-place-list selectable></gmp-place-list>

This class extends HTMLElement .

This class implements PlaceListElementOptions .

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

Constructor

 PlaceListElement

PlaceListElement([options])

Parameters:

options : PlaceListElementOptions optional

Properties

 places

Type:

 Array 
< Place 
>

Read only. Array of Place objects containing the IDs, locations, and viewports of the currently rendered places.

 selectable

Type: boolean

Whether or not the list items are selectable. If true, the list items will be buttons that dispatch the gmp-placeselect event when clicked. Accessible keyboard navigation and selection is also supported.

HTML attribute:

<gmp-place-list selectable></gmp-place-list>

Methods

 addEventListener

addEventListener(type, listener[, options])

Parameters:

type : string A case-sensitive string representing the event type to listen for.
listener : EventListener | EventListenerObject The object that receives a notification. This must be a function or an object with the handleEvent method
options : boolean| AddEventListenerOptions optional See options . Custom events only support capture and passive .

Return Value: void

Sets up a function that will be called whenever the specified event is delivered to the target. See addEventListener .

 configureFromSearchByTextRequest

configureFromSearchByTextRequest(request)

Parameters:

request : SearchByTextRequest The request to render results for. The fields property of the SearchByTextRequest is not required.

Return Value:

 Promise 
<void>

A promise that resolves once place data is loaded and rendered.

Configures the widget to render search results from a Places Text Search API request.

 configureFromSearchNearbyRequest

configureFromSearchNearbyRequest(request)

Parameters:

request : SearchNearbyRequest The request to render results for. The fields property of the SearchNearbyRequest is not required.

Return Value:

 Promise 
<void>

A promise that resolves once place data is loaded and rendered.

Configures the widget to render search results from a Places Nearby Search API request.

 removeEventListener

removeEventListener(type, listener[, options])

Parameters:

type : string A string which specifies the type of event for which to remove an event listener.
listener : EventListener | EventListenerObject The event listener of the event handler to remove from the event target.
options : boolean| EventListenerOptions optional See options .

Return Value: void

Removes an event listener previously registered with addEventListener from the target. See removeEventListener .

Events

 gmp-load

function(event)

Arguments:

event : Event

This event is fired when the element loads and renders its content. This event does not bubble.

 gmp-placeselect

function(event)

Arguments:

event : PlaceListPlaceSelectEvent

This event is fired when a user selects a place. Contains a Place object and the index of the selected place in the list.

 gmp-requesterror

function(event)

Arguments:

event : Event

This event is fired when a request to the backend was denied (e.g. incorrect API key). This event does not bubble.

PlaceListElementOptions interface

google.maps.places . PlaceListElementOptions interface

Options for PlaceListElement .

Properties
`selectable optional`	Type: `boolean optional` See `PlaceListElement.selectable`

PlaceListPlaceSelectEvent class

google.maps.places . PlaceListPlaceSelectEvent class

This event is emitted by the PlaceListElement when the user selects a place.

This class extends Event .

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

Properties
`index`	Type: `number` The list index of the selected place.
`place`	Type: `Place` A `Place` object containing the ID, location, and viewport of the selected place.

Autocomplete class

google.maps.places . Autocomplete class

A widget that provides Place predictions based on a user's text input. It attaches to an input element of type text , and listens for text entry in that field. The list of predictions is presented as a drop-down list, and is updated as text is entered.

This class extends MVCObject .

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

Constructor

 Autocomplete

Autocomplete(inputField[, opts])

Parameters:

inputField : HTMLInputElement The <input> text field to which the Autocomplete should be attached.
opts : AutocompleteOptions optional Options.

Creates a new instance of Autocomplete that attaches to the specified input text field with the given options.

Methods

 getBounds

getBounds()

Parameters: None

Return Value:

 LatLngBounds 
|undefined

The biasing bounds.

Returns the bounds to which predictions are biased.

 getFields

getFields()

Parameters: None

Return Value:

 Array 
<string>|undefined

Returns the fields to be included for the Place in the details response when the details are successfully retrieved. For a list of fields see

 PlaceResult

 getPlace

getPlace()

Parameters: None

Return Value:

 PlaceResult

The Place selected by the user.

Returns the details of the Place selected by user if the details were successfully retrieved. Otherwise returns a stub Place object, with the name property set to the current value of the input field.

 setBounds

setBounds(bounds)

Parameters:

bounds : LatLngBounds | LatLngBoundsLiteral optional The biasing bounds.

Return Value: None

Sets the preferred area within which to return Place results. Results are biased towards, but not restricted to, this area.

 setComponentRestrictions

setComponentRestrictions(restrictions)

Parameters:

restrictions : ComponentRestrictions optional The restrictions to use.

Return Value: None

Sets the component restrictions. Component restrictions are used to restrict predictions to only those within the parent component. For example, the country.

 setFields

setFields(fields)

Parameters:

fields : Array <string> optional

Return Value: None

Sets the fields to be included for the Place in the details response when the details are successfully retrieved. For a list of fields see

 PlaceResult

 setOptions

setOptions(options)

Parameters:

options : AutocompleteOptions optional

Return Value: None

 setTypes

setTypes(types)

Parameters:

types : Array <string> optional The types of predictions to be included.

Return Value: None

Sets the types of predictions to be returned. For supported types, see the developer's guide . If no types are specified, all types will be returned.

Inherited:

 addListener

 bindTo

get

 notify

set

 setValues

 unbind

 unbindAll

Events
`place_changed`	`function()` Arguments: None This event is fired when a `PlaceResult` is made available for a Place the user has selected. If the user enters the name of a Place that was not suggested by the control and presses the Enter key, or if a Place Details request fails, the `PlaceResult` contains the user input in the `name` property, with no other properties defined.

AutocompleteOptions interface

google.maps.places . AutocompleteOptions interface

The options that can be set on an Autocomplete object.

Properties
`bounds optional`	Type: `LatLngBounds \| LatLngBoundsLiteral optional` The area in which to search for places.
`componentRestrictions optional`	Type: `ComponentRestrictions optional` The component restrictions. Component restrictions are used to restrict predictions to only those within the parent component. For example, the country.
`fields optional`	Type: `Array <string> optional` Fields to be included for the Place in the details response when the details are successfully retrieved, 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"` ). The default is `['ALL']` .
~~`placeIdOnly`~~ optional	Deprecated: `placeIdOnly` is deprecated as of January 15, 2019, and will be turned off on January 15, 2020. Use `AutocompleteOptions.fields` instead: `fields: ['place_id', 'name', 'types']` . Type: `boolean optional` Whether to retrieve only Place IDs. The PlaceResult made available when the place_changed event is fired will only have the place_id, types and name fields, with the place_id, types and description returned by the Autocomplete service. Disabled by default.
`strictBounds optional`	Type: `boolean optional` A boolean value, indicating that the Autocomplete widget should only return those places that are inside the bounds of the Autocomplete widget at the time the query is sent. Setting strictBounds to `false` (which is the default) will make the results biased towards, but not restricted to, places contained within the bounds.
`types optional`	Type: `Array <string> optional` The types of predictions to be returned. For supported types, see the developer's guide . If no types are specified, all types will be returned.

google.maps.places . SearchBox class

A widget that provides query predictions based on a user's text input. It attaches to an input element of type text , and listens for text entry in that field. The list of predictions is presented as a drop-down list, and is updated as text is entered.

This class extends MVCObject .

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

 SearchBox

SearchBox(inputField[, opts])

Parameters:

inputField : HTMLInputElement
opts : SearchBoxOptions optional

Creates a new instance of SearchBox that attaches to the specified input text field with the given options.

Inherited:

 addListener

 bindTo

get

 notify

set

 setValues

 unbind

 unbindAll

Events
`places_changed`	`function()` Arguments: None This event is fired when the user selects a query, `getPlaces` should be used to get new places.

SearchBoxOptions interface

google.maps.places . SearchBoxOptions interface

The options that can be set on a SearchBox object.

Properties
`bounds optional`	Type: `LatLngBounds \| LatLngBoundsLiteral optional` The area towards which to bias query predictions. Predictions are biased towards, but not restricted to, queries targeting these bounds.

Places Widgets Stay organized with collections Save and categorize content based on your preferences.

PlaceAutocompleteElement class

Constructor

Properties

Parts

Methods

Events

PlaceAutocompleteElementOptions interface

Properties

PlaceAutocompletePlaceSelectEvent class

Properties

PlacePredictionSelectEvent class

Properties

PlaceAutocompleteRequestErrorEvent class

PlaceDetailsElement class

Constructor

Properties

Methods

Events

PlaceDetailsElementOptions interface

Properties

PlaceDetailsSize constants

Constants

PlaceListElement class

Constructor

Properties

Methods

Events

PlaceListElementOptions interface

Properties

PlaceListPlaceSelectEvent class

Properties

Autocomplete class

Constructor

Methods

Events

AutocompleteOptions interface

Properties

SearchBox class

Constructor

Methods

Events

SearchBoxOptions interface

Properties

Places Widgets