The Place Autocomplete Widget creates a text input field, supplies place predictions in a UI pick list, and returns place details in response to the user's selection. Use the Place Autocomplete Widget to embed a complete self-contained autocomplete user interface on your web page.
Prerequisites
To use Place Autocomplete, you must enable "Places API (new)" on your Google Cloud project. See Get started for details.
What's new
Place Autocomplete has been improved in the following ways:
- The Autocomplete widget UI supports regional localization (including RTL languages), for the text input placeholder, predictions list logo, and the place predictions.
- Enhanced accessibility, including support for screen readers and keyboard interaction.
- The Autocomplete widget returns the new Place class to simplify handling of the returned object.
- Better support for mobile devices and small screens.
- Better performance and improved graphical appearance.
Add an Autocomplete widget
The Autocomplete widget creates
a text input field, supplies place predictions in a UI pick list, and returns place details in
response to a user click using the gmp-select
listener. This section shows you how to
add an autocomplete widget to a web page, or a Google map.
Add an Autocomplete widget to a web page
To add the Autocomplete widget to a web page, create a new google.maps.places.PlaceAutocompleteElement
, and append it to
the page as shown in the following example:
TypeScript
// Request needed libraries. await google . maps . importLibrary ( "places" ) as google . maps . PlacesLibrary ; // Create the input HTML element, and append it. //@ts-ignore const placeAutocomplete = new google . maps . places . PlaceAutocompleteElement (); //@ts-ignore document . body . appendChild ( placeAutocomplete );
JavaScript
// Request needed libraries. await google . maps . importLibrary ( "places" ); // Create the input HTML element, and append it. //@ts-ignore const placeAutocomplete = new google . maps . places . PlaceAutocompleteElement (); //@ts-ignore document . body . appendChild ( placeAutocomplete );
Add an Autocomplete widget to a map
If your billing address is outside of the European Economic Area (EEA) , you may also use the Autocomplete widget with a Google Map.
To add an Autocomplete widget to a map, create a new google.maps.places.PlaceAutocompleteElement
instance, append the PlaceAutocompleteElement
to a div
, and push it onto the map as a custom
control, as shown in the following example:
TypeScript
//@ts-ignore const placeAutocomplete = new google . maps . places . PlaceAutocompleteElement (); //@ts-ignore placeAutocomplete . id = 'place-autocomplete-input' ; placeAutocomplete . locationBias = center ; const card = document . getElementById ( 'place-autocomplete-card' ) as HTMLElement ; //@ts-ignore card . appendChild ( placeAutocomplete ); map . controls [ google . maps . ControlPosition . TOP_LEFT ]. push ( card );
JavaScript
//@ts-ignore const placeAutocomplete = new google . maps . places . PlaceAutocompleteElement (); //@ts-ignore placeAutocomplete . id = 'place-autocomplete-input' ; placeAutocomplete . locationBias = center ; const card = document . getElementById ( 'place-autocomplete-card' ); //@ts-ignore card . appendChild ( placeAutocomplete ); map . controls [ google . maps . ControlPosition . TOP_LEFT ]. push ( card );
Constrain Autocomplete predictions
By default, Place Autocomplete presents all place types, biased for predictions near the user's location, and fetches all available data fields for the user's selected place. Set PlaceAutocompleteElementOptions to present more relevant predictions, by restricting or biasing results.
Restricting results causes the Autocomplete widget to ignore any results that are outside of the restriction area. A common practice is to restrict results to the map bounds. Biasing results makes the Autocomplete widget show results within the specified area, but some matches may be outside of that area.
If you don't supply any bounds or a map viewport, the API will attempt to detect the user's location from their IP address, and will bias the results to that location. Set a bounds whenever possible. Otherwise, different users may receive different predictions. Also, to generally improve predictions it is important to provide a sensible viewport such as one that you set by panning or zooming on the map, or a developer-set viewport based on device location and radius. When a radius is not available, 5 km is considered a sensible default for Place Autocomplete. Don't set a viewport with zero radius (a single point), a viewport that is only a few meters across (less than 100 m.), or a viewport that spans the globe.
Restrict place search by country
To restrict place search to one or more specific countries, use the includedRegionCodes
property to specify the country code(s) as shown in the following snippet:
const pac = new google . maps . places . PlaceAutocompleteElement ({ includedRegionCodes : [ 'us' , 'au' ], });
Restrict place search to map bounds
To restrict place search to a map's bounds, use the locationRestrictions
property to add the bounds, as shown in the following snippet:
const pac = new google . maps . places . PlaceAutocompleteElement ({ locationRestriction : map . getBounds (), });
When restricting to map bounds, be sure to add a listener to update the bounds when they change:
map . addListener ( 'bounds_changed' , () => { autocomplete . locationRestriction = map . getBounds (); });
To remove the locationRestriction
, set it to null
.
Bias place search results
Bias place search results to a circle area by using the locationBias
property, and
passing a radius, as shown here:
const autocomplete = new google . maps . places . PlaceAutocompleteElement ({ locationBias : { radius : 100 , center : { lat : 50.064192 , lng : - 130.605469 }}, });
To remove the locationBias
, set it to null
.
Restrict place search results to certain types
Restrict place search results to certain types of places by using the includedPrimaryTypes
property, and specifying one or more types, as shown here:
const autocomplete = new google . maps . places . PlaceAutocompleteElement ({ includedPrimaryTypes : [ 'establishment' ], });
For a complete list of supported types, see Place type tables A and B .
Get place details
To get place details for the selected place, add a gmp-select
listener to
the PlaceAutocompleteElement
, as shown in the following example:
TypeScript
// Add the gmp-placeselect listener, and display the results. //@ts-ignore placeAutocomplete . addEventListener ( 'gmp-select' , async ({ placePrediction }) = > { const place = placePrediction . toPlace (); await place . fetchFields ({ fields : [ 'displayName' , 'formattedAddress' , 'location' ] }); selectedPlaceTitle . textContent = 'Selected Place:' ; selectedPlaceInfo . textContent = JSON . stringify ( place . toJSON (), /* replacer */ null , /* space */ 2 ); });
JavaScript
// Add the gmp-placeselect listener, and display the results. //@ts-ignore placeAutocomplete . addEventListener ( 'gmp-select' , async ({ placePrediction }) = > { const place = placePrediction . toPlace (); await place . fetchFields ({ fields : [ 'displayName' , 'formattedAddress' , 'location' ] }); selectedPlaceTitle . textContent = 'Selected Place:' ; selectedPlaceInfo . textContent = JSON . stringify ( place . toJSON (), /* replacer */ null , /* space */ 2 ); });
In the preceding example, the event listener returns an object of Place class
.
Call place.fetchFields()
to get the Place Details data fields
needed for your application.
The listener in the next example requests place information and displays it on a map.
TypeScript
// Add the gmp-placeselect listener, and display the results on the map. //@ts-ignore placeAutocomplete . addEventListener ( 'gmp-select' , async ({ placePrediction }) = > { const place = placePrediction . toPlace (); await place . fetchFields ({ fields : [ 'displayName' , 'formattedAddress' , 'location' ] }); // If the place has a geometry, then present it on a map. if ( place . viewport ) { map . fitBounds ( place . viewport ); } else { map . setCenter ( place . location ); map . setZoom ( 17 ); } let content = '<div id="infowindow-content">' + '<span id="place-displayname" class="title">' + place . displayName + '</span><br />' + '<span id="place-address">' + place . formattedAddress + '</span>' + '</div>' ; updateInfoWindow ( content , place . location ); marker . position = place . location ; });
JavaScript
// Add the gmp-placeselect listener, and display the results on the map. //@ts-ignore placeAutocomplete . addEventListener ( 'gmp-select' , async ({ placePrediction }) = > { const place = placePrediction . toPlace (); await place . fetchFields ({ fields : [ 'displayName' , 'formattedAddress' , 'location' ] }); // If the place has a geometry, then present it on a map. if ( place . viewport ) { map . fitBounds ( place . viewport ); } else { map . setCenter ( place . location ); map . setZoom ( 17 ); } let content = '<div id="infowindow-content">' + '<span id="place-displayname" class="title">' + place . displayName + '</span><br />' + '<span id="place-address">' + place . formattedAddress + '</span>' + '</div>' ; updateInfoWindow ( content , place . location ); marker . position = place . location ; });
Example maps
This section contains the complete code for the example maps featured on this page.
Autocomplete element
This example adds an Autocomplete widget to a web page, and displays the results for each selected place.
TypeScript
async function initMap () : Promise<void> { // Request needed libraries. await google . maps . importLibrary ( "places" ) as google . maps . PlacesLibrary ; // Create the input HTML element, and append it. //@ts-ignore const placeAutocomplete = new google . maps . places . PlaceAutocompleteElement (); //@ts-ignore document . body . appendChild ( placeAutocomplete ); // Inject HTML UI. const selectedPlaceTitle = document . createElement ( 'p' ); selectedPlaceTitle . textContent = '' ; document . body . appendChild ( selectedPlaceTitle ); const selectedPlaceInfo = document . createElement ( 'pre' ); selectedPlaceInfo . textContent = '' ; document . body . appendChild ( selectedPlaceInfo ); // Add the gmp-placeselect listener, and display the results. //@ts-ignore placeAutocomplete . addEventListener ( 'gmp-select' , async ({ placePrediction }) = > { const place = placePrediction . toPlace (); await place . fetchFields ({ fields : [ 'displayName' , 'formattedAddress' , 'location' ] }); selectedPlaceTitle . textContent = 'Selected Place:' ; selectedPlaceInfo . textContent = JSON . stringify ( place . toJSON (), /* replacer */ null , /* space */ 2 ); }); } initMap ();
JavaScript
async function initMap () { // Request needed libraries. await google . maps . importLibrary ( "places" ); // Create the input HTML element, and append it. //@ts-ignore const placeAutocomplete = new google . maps . places . PlaceAutocompleteElement (); //@ts-ignore document . body . appendChild ( placeAutocomplete ); // Inject HTML UI. const selectedPlaceTitle = document . createElement ( 'p' ); selectedPlaceTitle . textContent = '' ; document . body . appendChild ( selectedPlaceTitle ); const selectedPlaceInfo = document . createElement ( 'pre' ); selectedPlaceInfo . textContent = '' ; document . body . appendChild ( selectedPlaceInfo ); // Add the gmp-placeselect listener, and display the results. //@ts-ignore placeAutocomplete . addEventListener ( 'gmp-select' , async ({ placePrediction }) = > { const place = placePrediction . toPlace (); await place . fetchFields ({ fields : [ 'displayName' , 'formattedAddress' , 'location' ] }); selectedPlaceTitle . textContent = 'Selected Place:' ; selectedPlaceInfo . textContent = JSON . stringify ( place . toJSON (), /* replacer */ null , /* space */ 2 ); }); } initMap ();
CSS
/* * Always set the map height explicitly to define the size of the div element * that contains the map. */ # map { height : 100 % ; } /* * Optional: Makes the sample page fill the window. */ html , body { height : 100 % ; margin : 0 ; padding : 0 ; } p { font-family : Roboto , sans-serif ; font-weight : bold ; }
HTML
<html> <head> <title>Place Autocomplete element</title> <link rel="stylesheet" type="text/css" href="./style.css" /> <script type="module" src="./index.js"></script> </head> <body> <p style="font-family: roboto, sans-serif">Search for a place here:</p> <!-- prettier-ignore --> <script>(g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))}) ({key: "AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8", v: "weekly"});</script> </body> </html>
Try Sample
Autocomplete map
This example shows you how to add an Autocomplete widget to a Google map.
TypeScript
let map : google.maps.Map ; let marker : google.maps.marker.AdvancedMarkerElement ; let infoWindow : google.maps.InfoWindow ; let center = { lat : 40.749933 , lng : - 73.98633 }; // New York City async function initMap () : Promise<void> { // Request needed libraries. //@ts-ignore const [{ Map }, { AdvancedMarkerElement }] = await Promise . all ([ google . maps . importLibrary ( "marker" ), google . maps . importLibrary ( "places" ) ]); // Initialize the map. map = new google . maps . Map ( document . getElementById ( 'map' ) as HTMLElement , { center , zoom : 13 , mapId : '4504f8b37365c3d0' , mapTypeControl : false , }); //@ts-ignore const placeAutocomplete = new google . maps . places . PlaceAutocompleteElement (); //@ts-ignore placeAutocomplete . id = 'place-autocomplete-input' ; placeAutocomplete . locationBias = center ; const card = document . getElementById ( 'place-autocomplete-card' ) as HTMLElement ; //@ts-ignore card . appendChild ( placeAutocomplete ); map . controls [ google . maps . ControlPosition . TOP_LEFT ]. push ( card ); // Create the marker and infowindow. marker = new google . maps . marker . AdvancedMarkerElement ({ map , }); infoWindow = new google . maps . InfoWindow ({}); // Add the gmp-placeselect listener, and display the results on the map. //@ts-ignore placeAutocomplete . addEventListener ( 'gmp-select' , async ({ placePrediction }) = > { const place = placePrediction . toPlace (); await place . fetchFields ({ fields : [ 'displayName' , 'formattedAddress' , 'location' ] }); // If the place has a geometry, then present it on a map. if ( place . viewport ) { map . fitBounds ( place . viewport ); } else { map . setCenter ( place . location ); map . setZoom ( 17 ); } let content = '<div id="infowindow-content">' + '<span id="place-displayname" class="title">' + place . displayName + '</span><br />' + '<span id="place-address">' + place . formattedAddress + '</span>' + '</div>' ; updateInfoWindow ( content , place . location ); marker . position = place . location ; }); } // Helper function to create an info window. function updateInfoWindow ( content , center ) { infoWindow . setContent ( content ); infoWindow . setPosition ( center ); infoWindow . open ({ map , anchor : marker , shouldFocus : false , }); } initMap ();
JavaScript
let map ; let marker ; let infoWindow ; let center = { lat : 40.749933 , lng : - 73.98633 }; // New York City async function initMap () { // Request needed libraries. //@ts-ignore const [{ Map }, { AdvancedMarkerElement }] = await Promise . all ([ google . maps . importLibrary ( "marker" ), google . maps . importLibrary ( "places" ) ]); // Initialize the map. map = new google . maps . Map ( document . getElementById ( 'map' ), { center , zoom : 13 , mapId : '4504f8b37365c3d0' , mapTypeControl : false , }); //@ts-ignore const placeAutocomplete = new google . maps . places . PlaceAutocompleteElement (); //@ts-ignore placeAutocomplete . id = 'place-autocomplete-input' ; placeAutocomplete . locationBias = center ; const card = document . getElementById ( 'place-autocomplete-card' ); //@ts-ignore card . appendChild ( placeAutocomplete ); map . controls [ google . maps . ControlPosition . TOP_LEFT ]. push ( card ); // Create the marker and infowindow. marker = new google . maps . marker . AdvancedMarkerElement ({ map , }); infoWindow = new google . maps . InfoWindow ({}); // Add the gmp-placeselect listener, and display the results on the map. //@ts-ignore placeAutocomplete . addEventListener ( 'gmp-select' , async ({ placePrediction }) = > { const place = placePrediction . toPlace (); await place . fetchFields ({ fields : [ 'displayName' , 'formattedAddress' , 'location' ] }); // If the place has a geometry, then present it on a map. if ( place . viewport ) { map . fitBounds ( place . viewport ); } else { map . setCenter ( place . location ); map . setZoom ( 17 ); } let content = '<div id="infowindow-content">' + '<span id="place-displayname" class="title">' + place . displayName + '</span><br />' + '<span id="place-address">' + place . formattedAddress + '</span>' + '</div>' ; updateInfoWindow ( content , place . location ); marker . position = place . location ; }); } // Helper function to create an info window. function updateInfoWindow ( content , center ) { infoWindow . setContent ( content ); infoWindow . setPosition ( center ); infoWindow . open ({ map , anchor : marker , shouldFocus : false , }); } initMap ();
CSS
/* * Always set the map height explicitly to define the size of the div element * that contains the map. */ # map { height : 100 % ; } /* * Optional: Makes the sample page fill the window. */ html , body { height : 100 % ; margin : 0 ; padding : 0 ; } # place-autocomplete-card { background-color : #fff ; border-radius : 5 px ; box-shadow : rgba ( 0 , 0 , 0 , 0.35 ) 0 px 5 px 15 px ; margin : 10 px ; padding : 5 px ; font-family : Roboto , sans-serif ; font-size : large ; font-weight : bold ; } gmp-place-autocomplete { width : 300 px ; } # infowindow-content . title { font-weight : bold ; } # map # infowindow-content { display : inline ; }
HTML
<html> <head> <title>Place Autocomplete map</title> <link rel="stylesheet" type="text/css" href="./style.css" /> <script type="module" src="./index.js"></script> </head> <body> <div class="place-autocomplete-card" id="place-autocomplete-card"> <p>Search for a place here:</p> </div> <div id="map"></div> <!-- prettier-ignore --> <script>(g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))}) ({key: "AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8", v: "weekly"});</script> </body> </html>
Try Sample
Use the Place Picker component
The place picker component is a text input that allows end users to search for a specific address or place using autocomplete. It is part of the Extended Component Library , a set of web components that help developers build better maps and location features faster.
Use the Place Picker configurator to create embeddable code for a custom Place Picker component, then export it to be used with popular frameworks like React and Angular or no framework at all.
