Places UI Kit: A ready-to-use library that provides room for customization and low-code development. Try it out, and share yourinput on your UI Kit experience.

Migrate to the new Place Autocomplete

European Economic Area (EEA) developers If your billing address is in the European Economic Area, effective on 8 July 2025, the Google Maps Platform EEA Terms of Service will apply to your use of the Services. Functionality varies by region.Learn more.

Place Autocomplete is a feature of the Places library in theMaps JavaScript API. You can use autocomplete to give yourapplications the type-ahead-search behavior of the Google Maps search field.

This page explains the differences between legacy and new Place Autocompletefeatures. In both versions there are two general ways to integrate Autocomplete:

Programmatic interface: For developers seekinggreater customization and control over the autocomplete experience.
Place Autocomplete widget: A search bar which can beembedded on a map or web page.

Autocomplete programmatic interface

The following table lists some of the main differences in the use ofprogrammatic Place Autocomplete betweenPlaces Autocomplete Service(legacy) andAutocompleteData API (new):

`PlacesService` (Legacy)	`Place` (New)
Places Autocomplete Service reference	Autocomplete Data (new) reference
`AutocompletionRequest`	`AutocompleteRequest`
`AutocompleteService.getPlacePredictions`	`AutocompleteSuggestion.fetchAutocompleteSuggestions`
`AutocompletePrediction`	`PlacePrediction`
Methods require the use of a callback to handle the results object and`PlacesServiceStatus` response.	Uses Promises, and works asynchronously.
Methods require a`PlacesServiceStatus` check.	No required status check, can use standard error handling.Learn more.
Place data fields are set as options when the`Autocomplete` instance is created.	Place data fields are set later when`fetchFields()` is called.
Query predictions are supported (`SearchBox` only).	Query predictions are not available in the`Autocomplete` class.
Limited to a fixed set ofplace types andplace data fields.	Access to an expanded selection ofplace types andplace data fields.

The following are used by both legacy and new Autocomplete APIs:

Code comparison (programmatic)

This section compares code for autocomplete to illustrate the differencesbetween the Places Service and thePlace class, for programmatic interfaces.

Retrieve autocomplete predictions (legacy)

The legacy Places Service lets you retrieveautocomplete predictions programmatically, for more control over the userinterface than is offered by theAutocomplete class. In the following example,a single request is made for "par", with aAutocompletionRequest consisting ofthe input value and a set of bounds for biasing the prediction. The examplereturns a list ofAutocompletePredictioninstances, and shows the description for each one. The example function alsocreates a session token and applies it to the request.

functioninit(){constplaceInfo=document.getElementById("prediction");constservice=newgoogle.maps.places.AutocompleteService();constplacesService=newgoogle.maps.places.PlacesService(placeInfo);varsessionToken=newgoogle.maps.places.AutocompleteSessionToken();// Define request options.letrequest={input:"par",sessionToken:sessionToken,bounds:{west:-122.44,north:37.8,east:-122.39,south:37.78,},}// Display the query string.consttitle=document.getElementById("title");title.appendChild(document.createTextNode('Place predictions for "'+request.input+'":'),);// Perform the query and display the results.constdisplaySuggestions=function(predictions,status){// Check the status of the Places Service.if(status!=google.maps.places.PlacesServiceStatus.OK||!predictions){alert(status);return;}predictions.forEach((prediction)=>{constli=document.createElement("li");li.appendChild(document.createTextNode(prediction.description));document.getElementById("results").appendChild(li);});constplaceRequest={placeId:predictions[0].place_id,fields:["name","formatted_address"],};placesService.getDetails(placeRequest,(place,status)=>{if(status==google.maps.places.PlacesServiceStatus.OK &&place){placeInfo.textContent=`          First predicted place:${place.name} at${place.formatted_address}`}});};// Show the results of the query.service.getPlacePredictions(request,displaySuggestions);}

Retrieve autocomplete predictions (new)

The new Place class also lets you retrieveautocomplete predictions programmatically for more control over the userinterface than is offered by thePlaceAutocompleteElement class. In thefollowing example, a single request is made for "par", with anAutocompleteRequest consisting of the input value and a set of bounds forbiasing the prediction. The example returns a list ofplacePredictioninstances and shows the description for each one. The example function alsocreates a session token and applies it to the request.

asyncfunctioninit(){letsessionToken=newgoogle.maps.places.AutocompleteSessionToken();// Define request options.letrequest={input:"par",sessionToken:sessionToken,locationBias:{west:-122.44,north:37.8,east:-122.39,south:37.78,},};// Display the query string.consttitle=document.getElementById("title");title.appendChild(document.createTextNode('Place predictions for "'+request.input+'":'),);// Perform the query and display the results.const{suggestions}=awaitgoogle.maps.places.AutocompleteSuggestion.fetchAutocompleteSuggestions(request);constresultsElement=document.getElementById("results");for(letsuggestionofsuggestions){constplacePrediction=suggestion.placePrediction;constlistItem=document.createElement("li");listItem.appendChild(document.createTextNode(placePrediction.text.text),);resultsElement.appendChild(listItem);}// Show the first predicted place.letplace=suggestions[0].placePrediction.toPlace();awaitplace.fetchFields({fields:["displayName","formattedAddress"],});constplaceInfo=document.getElementById("prediction");placeInfo.textContent=`    First predicted place:${place.displayName} at${place.formattedAddress}`}

Place autocomplete widget

The following table lists some of the main differences in the use ofautocomplete widgets between the Places service (legacy), and the Place class(new):

Places Service (Legacy)	Place (New)
`Autocomplete` class for place predictions.	`PlaceAutocompleteElement` class for place predictions.
`SearchBox` class for query predictions.	Query predictions are not available in the`Autocomplete` class.
Only the default input placeholder text is localized.	Text input placeholder, predictions list logo, and place predictions all support regional localization.
Widget uses`setBounds()` or`autocomplete.bindTo()` to constrain (bias) the search to the specified bounds, and`strictBounds` to restrict results to the specified bounds.	Widget uses the`locationBias` property to bias results to the specified bounds, and the`locationRestriction` property to restrict the search to the specified bounds.
Widgets can only be integrated by using a standard HTML input element.	Widget can be integrated using a standard HTML input element or a`gmp-place-autocomplete` element.
When using the widget, it is possible for users to request things that may not be valid (for example "bisneyland"); this case must be explicitly handled.	The widget will only return results for the provided suggestions, and cannot issue requests for arbitrary values; therefore there is no need to handle potentially invalid requests.
Returns legacy`PlaceResult` instance.	Returns`Place` instance.
Place data fields are set as options for the`Autocomplete` object.	Place data fields are set when the user makes a selection and`fetchFields()` is called.
Limited to a fixed set ofplace types andplace data fields.	Access to an expanded selection ofplace types andplace data fields.

Code comparison (widgets)

This section compares code for autocomplete to illustrate the differencesbetween the legacy Place Autocomplete Widget and the new Place Autocompleteelement.

Place Autocomplete Widget (legacy)

The Places Service offers two types of autocompletewidgets, which you can add by using theAutocomplete andSearchBox classes.Each kind of widget can be added to a map as a map control, or embedded directlyonto a web page. The following code example shows embedding anAutocompletewidget as a map control.

TheAutocomplete widget constructor takes two arguments:
- An HTMLinput element of typetext. This is the input field that theautocomplete service will monitor and attach its results to.
- An optionalAutocompleteOptionsargument, where you can specify further options to constrain the query.
To set bounds, theAutocomplete instance can be explicitly bound to themap by callingautocomplete.bindTo().
Specify place data fields in the options for autocomplete.

functioninitMap(){constmap=newgoogle.maps.Map(document.getElementById("map"),{center:{lat:40.749933,lng:-73.98633},zoom:13,mapTypeControl:false,});constcard=document.getElementById("pac-card");constinput=document.getElementById("pac-input");constoptions={fields:["formatted_address","geometry","name"],strictBounds:false,};map.controls[google.maps.ControlPosition.TOP_LEFT].push(card);constautocomplete=newgoogle.maps.places.Autocomplete(input,options);// Bind the map's bounds (viewport) property to the autocomplete object,// so that the autocomplete requests use the current map bounds for the// bounds option in the request.autocomplete.bindTo("bounds",map);constinfowindow=newgoogle.maps.InfoWindow();constinfowindowContent=document.getElementById("infowindow-content");infowindow.setContent(infowindowContent);constmarker=newgoogle.maps.Marker({map,anchorPoint:newgoogle.maps.Point(0,-29),});autocomplete.addListener("place_changed",()=>{infowindow.close();marker.setVisible(false);constplace=autocomplete.getPlace();if(!place.geometry||!place.geometry.location){// User entered the name of a Place that was not suggested and// pressed the Enter key, or the Place Details request failed.window.alert("No details available for input: '"+place.name+"'");return;}// If the place has a geometry, then present it on a map.if(place.geometry.viewport){map.fitBounds(place.geometry.viewport);}else{map.setCenter(place.geometry.location);map.setZoom(17);}marker.setPosition(place.geometry.location);marker.setVisible(true);infowindowContent.children["place-name"].textContent=place.name;infowindowContent.children["place-address"].textContent=place.formatted_address;infowindow.open(map,marker);});}

Place Autocomplete Widget (New)

The Place class offers thePlaceAutocompleteElement,anHTMLElement subclass which provides a UI component that can be added to amap as a map control, or embedded directly onto a web page. The following codeexample shows embedding anPlaceAutocompleteElement widget as a map control.

The Place Autocomplete Widget has been improved in the following ways:

The Autocomplete widget UI supports regional localization (including RTLlanguages), for the text input placeholder, predictions list logo, and theplace predictions.
Enhanced accessibility, including support for screen readers and keyboardinteraction.
The Autocomplete widget returns the newPlace class to simplify handlingof the returned object.
Better support for mobile devices and small screens.
Better performance and improved graphical appearance.

Key implementation differences include:

ThePlaceAutocompleteElement provides its own input field, and is directlyinserted into the page using HTML or JavaScript (as opposed to beingprovided an existing input element).
Query predictions are not available in theAutocompleteclass.
ThePlaceAutocompleteElement is constructed usingPlaceAutocompleteElementOptions.
- Place data fields are specified at selection time (whenfetchFields()is called).
Set bounds by using either thelocationBounds orlocationRestrictionoption.

letmap;letmarker;letinfoWindow;asyncfunctioninitMap(){// Request needed libraries.const[{Map},{AdvancedMarkerElement}]=awaitPromise.all([google.maps.importLibrary("marker"),google.maps.importLibrary("places"),]);// Initialize the map.map=newgoogle.maps.Map(document.getElementById("map"),{center:{lat:40.749933,lng:-73.98633},zoom:13,mapId:"4504f8b37365c3d0",mapTypeControl:false,});constplaceAutocomplete=newgoogle.maps.places.PlaceAutocompleteElement({locationRestriction:map.getBounds(),});placeAutocomplete.id="place-autocomplete-input";constcard=document.getElementById("place-autocomplete-card");card.appendChild(placeAutocomplete);map.controls[google.maps.ControlPosition.TOP_LEFT].push(card);// Create the marker and infowindow.marker=newgoogle.maps.marker.AdvancedMarkerElement({map,});infoWindow=newgoogle.maps.InfoWindow({});// Add the gmp-select listener, and display the results on the map.placeAutocomplete.addEventListener("gmp-select",async(place)=>{constplace=event.placePrediction.toPlace();awaitplace.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);}letcontent='<div>'+'<span>'+place.displayName+'</span><br />'+'<span>'+place.formattedAddress+'</span>'+'</div>';updateInfoWindow(content,place.location);marker.position=place.location;});}// Helper function to create an info window.functionupdateInfoWindow(content,center){infoWindow.setContent(content);infoWindow.setPosition(center);infoWindow.open({map,anchor:marker,shouldFocus:false,});}

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-11-21 UTC.

Movatterモバイル変換

Migrate to the new Place Autocomplete Stay organized with collections Save and categorize content based on your preferences.