Introduction
Autocomplete is a feature of the Places library in the Maps JavaScript API. You can use autocomplete to give your applications the type-ahead-search behavior of the Google Maps search field. The autocomplete service can match on full words and substrings, resolving place names, addresses, and plus codes. Applications can therefore send queries as the user types, to provide on-the-fly place predictions. As defined by the Places API, a 'place' can be an establishment, a geographic location, or a prominent point of interest.
Getting started
Before using the Places library in the Maps JavaScript API, first ensure that the Places API is enabled in the Google Cloud Console, in the same project you set up for the Maps JavaScript API.
To view your list of enabled APIs:
- Go to the Google Cloud Console.
- Click the Select a project button, then select the same project you set up for the Maps JavaScript API and click Open.
- From the list of APIs on the Dashboard, look for Places API.
- If you see the API in the list, you’re all set. If the API is not listed,
enable it:
- At the top of the page, select ENABLE API to display the Library tab. Alternatively, from the left side menu, select Library.
- Search for Places API, then select it from the results list.
- Select ENABLE. When the process finishes, Places API appears in the list of APIs on the Dashboard.
Loading the library
The Places service is a self-contained library, separate from the main
Maps JavaScript API code. To use the functionality contained
within this library, you must first load it using the libraries
parameter in the Maps API bootstrap URL:
<script async
src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&libraries=places&callback=initMap">
</script>
See the Libraries Overview for more information.
Summary of classes
The API offers two types of autocomplete widgets, which you can add via
the Autocomplete
and SearchBox
classes respectively.
In addition, you can use the AutocompleteService
class to retrieve
autocomplete results programmatically (see the Maps JavaScript API Reference:
AutocompleteService class).
Below is a summary of the classes available:
-
Autocomplete
adds a text input field to your web page, and monitors that field for character entries. As the user enters text, autocomplete returns place predictions in the form of a dropdown pick list. When the user selects a place from the list, information about the place is returned to the autocomplete object, and can be retrieved by your application. See the details below.Figure 1: Autocomplete text field and pick list Figure 2: Completed address form -
SearchBox
adds a text input field to your web page, in much the same way asAutocomplete
. The differences are as follows:- The main difference lies in the
results that appear in the pick list.
SearchBox
supplies an extended list of predictions, which can include places (as defined by the Places API) plus suggested search terms. For example, if the user enters 'pizza in new', the pick list may include the phrase 'pizza in New York, NY' as well as the names of various pizza outlets. SearchBox
offers fewer options thanAutocomplete
for restricting the search. In the former, you can bias the search towards a givenLatLngBounds
. In the latter, you can restrict the search to a particular country and particular place types, as well as setting the bounds. For more information, see below.
Figure 3: A SearchBox presents search terms and place predictions. - The main difference lies in the
results that appear in the pick list.
- You can create an
AutocompleteService
object to retrieve predictions programmatically. CallgetPlacePredictions()
to retrieve matching places, or callgetQueryPredictions()
to retrieve matching places plus suggested search terms. Note:AutocompleteService
does not add any UI controls. Instead, the above methods return an array of prediction objects. Each prediction object contains the text of the prediction, as well as reference information and details of how the result matches the user input. See the details below.
Adding an Autocomplete widget
The Autocomplete
widget creates a text input field on your web page, supplies predictions of places in a UI pick
list, and returns place details in response to a getPlace()
request. Each entry in the
pick list corresponds to a single place (as defined by the Places API).
The Autocomplete
constructor takes two arguments:
- An HTML
input
element of typetext
. This is the input field that the autocomplete service will monitor and attach its results to. - An optional
AutocompleteOptions
argument, which can contain the following properties:- An array of data
fields
to be included in thePlace Details
response for the user's selectedPlaceResult
. If the property is not set or if['ALL']
is passed in, all available fields are returned and billed for (this is not recommended for production deployments). For a list of fields, seePlaceResult
. - An array of
types
that specifies an explicit type or a type collection, as listed in the supported types. If no type is specified, all types are returned. bounds
is agoogle.maps.LatLngBounds
object specifying the area in which to search for places. The results are biased towards, but not restricted to, places contained within these bounds.strictBounds
is aboolean
specifying whether the API must return only those places that are strictly within the region defined by the givenbounds
. The API does not return results outside this region even if they match the user input.componentRestrictions
can be used to restrict results to specific groups. Currently, you can usecomponentRestrictions
to filter by up to 5 countries. Countries must be passed as as a two-character, ISO 3166-1 Alpha-2 compatible country code. Multiple countries must be passed as a list of country codes.Note: If you receive unexpected results with a country code, verify that you are using a code which includes the countries, dependent territories, and special areas of geographical interest you intend. You can find code information at Wikipedia: List of ISO 3166 country codes or the ISO Online Browsing Platform.
placeIdOnly
can be used to instruct theAutocomplete
widget to retrieve only Place IDs. On callinggetPlace()
on theAutocomplete
object, thePlaceResult
made available will only have theplace id
,types
andname
properties set. You can use the returned place ID with calls to the Places, Geocoding, Directions or Distance Matrix services.
- An array of data
Constraining 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 Place Autocomplete options to present more relevant predictions based on your use case.
Set options at construction
The Autocomplete
constructor accepts an AutocompleteOptions
parameter to set constraints at widget creation. The following example sets the
bounds
, componentRestrictions
, and types
options to
request establishment
type places, favoring those within the specified geographic
area and restricting predictions to only places within the United States. Setting the
fields
option specifies what information to return about the user's selected place.
Call setOptions()
to change an option's value for an existing widget.
TypeScript
const center = { lat: 50.064192, lng: -130.605469 }; // Create a bounding box with sides ~10km away from the center point const defaultBounds = { north: center.lat + 0.1, south: center.lat - 0.1, east: center.lng + 0.1, west: center.lng - 0.1, }; const input = document.getElementById("pac-input") as HTMLInputElement; const options = { bounds: defaultBounds, componentRestrictions: { country: "us" }, fields: ["address_components", "geometry", "icon", "name"], strictBounds: false, }; const autocomplete = new google.maps.places.Autocomplete(input, options);
JavaScript
const center = { lat: 50.064192, lng: -130.605469 }; // Create a bounding box with sides ~10km away from the center point const defaultBounds = { north: center.lat + 0.1, south: center.lat - 0.1, east: center.lng + 0.1, west: center.lng - 0.1, }; const input = document.getElementById("pac-input"); const options = { bounds: defaultBounds, componentRestrictions: { country: "us" }, fields: ["address_components", "geometry", "icon", "name"], strictBounds: false, }; const autocomplete = new google.maps.places.Autocomplete(input, options);
Specify data fields
Specify data fields to avoid being billed for Places Data SKUs you don't need. Include the fields
property in the
AutocompleteOptions
that are passed to the widget constructor, as demonstrated in the previous
example, or call setFields()
on an existing Autocomplete
object.
autocomplete.setFields(["place_id", "geometry", "name"]);
Define biases and search-area boundaries for Autocomplete
You can bias the autocomplete results to favor an approximate location or area, in the following ways:
- Set the bounds on creation of the
Autocomplete
object. - Change the bounds on an existing
Autocomplete
. - Set the bounds to the map's viewport.
- Restrict the search to the bounds.
- Restrict the search to a specific country.
The previous example demonstrates setting bounds at creation. The following examples demonstrate the other biasing techniques.
Change the bounds of an existing Autocomplete
Call setBounds()
to change the search area on an existing
Autocomplete
to rectangular bounds.
TypeScript
const southwest = { lat: 5.6108, lng: 136.589326 }; const northeast = { lat: 61.179287, lng: 2.64325 }; const newBounds = new google.maps.LatLngBounds(southwest, northeast); autocomplete.setBounds(newBounds);
JavaScript
const southwest = { lat: 5.6108, lng: 136.589326 }; const northeast = { lat: 61.179287, lng: 2.64325 }; const newBounds = new google.maps.LatLngBounds(southwest, northeast); autocomplete.setBounds(newBounds);
Set the bounds to the map's viewport
Use bindTo()
to bias the results to the map's viewport,
even while that viewport changes.
TypeScript
autocomplete.bindTo("bounds", map);
JavaScript
autocomplete.bindTo("bounds", map);
Use unbind()
to unbind the Autocomplete predictions from the map's viewport.
TypeScript
autocomplete.unbind("bounds"); autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });
JavaScript
autocomplete.unbind("bounds"); autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });
Restrict the search to the current bounds
Set the strictBounds
option to restrict the results to the current bounds, whether based on map viewport or rectangular bounds.
autocomplete.setOptions({ strictBounds: true });
Restrict predictions to a specific country
Use the componentRestrictions
option or call setComponentRestrictions()
to restrict the
autocomplete search to a specific set of up to five countries.
TypeScript
autocomplete.setComponentRestrictions({ country: ["us", "pr", "vi", "gu", "mp"], });
JavaScript
autocomplete.setComponentRestrictions({ country: ["us", "pr", "vi", "gu", "mp"], });
Constrain place types
Use the types
option or call setTypes()
to constrain
predictions to certain place types. This constraint specifies a type or a type collection,
as listed in Place Types.
If no constraint is specified, all types are returned.
For the value of the types
option or the value passed to setTypes()
, you
can specify either:
An array containing up to five values from Table 1 or Table 2 from Place Types. For example:
types: ['hospital', 'pharmacy', 'bakery', 'country']
Or:
autocomplete.setTypes(['hospital', 'pharmacy', 'bakery', 'country']);
- Any one filter in Table 3 from Place Types. You can only specify a single value from Table 3.
The request will be rejected if:
- You specify more than five types.
- You specify any unrecognized types.
- You mix any types from Table 1 or Table 2 with any filter from Table 3.
The Places Autocomplete demo demonstrates the differences in predictions between different place types.
Getting place information
When a user selects a place from the predictions attached to the autocomplete
text field, the service fires a place_changed
event. To get place
details:
- Create an event handler for the
place_changed
event, and calladdListener()
on theAutocomplete
object to add the handler. - Call
Autocomplete.getPlace()
on theAutocomplete
object, to retrieve aPlaceResult
object, which you can then use to get more information about the selected place.
By default, when a user selects a place, autocomplete returns all of the
available data fields for the selected place, and you will be billed accordingly.
Use Autocomplete.setFields()
to specify which place data fields to return. Read more about the
PlaceResult
object, including a list of place data fields that
you can request. To avoid paying for data that you don't need, be sure to use Autocomplete.setFields()
to specify
only the place data that you will use.
The name
property contains the
description
from Places Autocomplete predictions. You can read more about the
description
in the
Places
Autocomplete documentation.
For address forms, it is useful to get the address in structured format. To
return the structured address for the selected place, call
Autocomplete.setFields()
and specify the address_components
field.
The following example uses autocomplete to fill the fields in an address form.
TypeScript
function fillInAddress() { // Get the place details from the autocomplete object. const place = autocomplete.getPlace(); let address1 = ""; let postcode = ""; // Get each component of the address from the place details, // and then fill-in the corresponding field on the form. // place.address_components are google.maps.GeocoderAddressComponent objects // which are documented at http://goo.gle/3l5i5Mr for (const component of place.address_components as google.maps.GeocoderAddressComponent[]) { // @ts-ignore remove once typings fixed const componentType = component.types[0]; switch (componentType) { case "street_number": { address1 = `${component.long_name} ${address1}`; break; } case "route": { address1 += component.short_name; break; } case "postal_code": { postcode = `${component.long_name}${postcode}`; break; } case "postal_code_suffix": { postcode = `${postcode}-${component.long_name}`; break; } case "locality": (document.querySelector("#locality") as HTMLInputElement).value = component.long_name; break; case "administrative_area_level_1": { (document.querySelector("#state") as HTMLInputElement).value = component.short_name; break; } case "country": (document.querySelector("#country") as HTMLInputElement).value = component.long_name; break; } } address1Field.value = address1; postalField.value = postcode; // After filling the form with address components from the Autocomplete // prediction, set cursor focus on the second address line to encourage // entry of subpremise information such as apartment, unit, or floor number. address2Field.focus(); }
JavaScript
function fillInAddress() { // Get the place details from the autocomplete object. const place = autocomplete.getPlace(); let address1 = ""; let postcode = ""; // Get each component of the address from the place details, // and then fill-in the corresponding field on the form. // place.address_components are google.maps.GeocoderAddressComponent objects // which are documented at http://goo.gle/3l5i5Mr for (const component of place.address_components) { // @ts-ignore remove once typings fixed const componentType = component.types[0]; switch (componentType) { case "street_number": { address1 = `${component.long_name} ${address1}`; break; } case "route": { address1 += component.short_name; break; } case "postal_code": { postcode = `${component.long_name}${postcode}`; break; } case "postal_code_suffix": { postcode = `${postcode}-${component.long_name}`; break; } case "locality": document.querySelector("#locality").value = component.long_name; break; case "administrative_area_level_1": { document.querySelector("#state").value = component.short_name; break; } case "country": document.querySelector("#country").value = component.long_name; break; } } address1Field.value = address1; postalField.value = postcode; // After filling the form with address components from the Autocomplete // prediction, set cursor focus on the second address line to encourage // entry of subpremise information such as apartment, unit, or floor number. address2Field.focus(); } window.initAutocomplete = initAutocomplete;
Customizing placeholder text
By default, the text field created by the autocomplete service contains
standard placeholder text. To modify the text, set the
placeholder
attribute on the input
element:
<input id="searchTextField" type="text" size="50" placeholder="Anything you want!">
Note: The default placeholder text is localized automatically. If you specify your own placeholder value, you must handle the localization of that value in your application. For information on how the Google Maps JavaScript API chooses the language to use, please read the documentation on localization.
See Styling the Autocomplete and SearchBox widgets to customize the widget appearance.
Adding a SearchBox widget
The
SearchBox
allows users to perform a text-based geographic
search, such as 'pizza in New York' or 'shoe stores near robson street'.
You can attach the SearchBox
to a text field and, as
text is entered, the service will return predictions in the
form of a drop-down pick list.
SearchBox
supplies an extended list of predictions, which
can include places (as defined by the Places API) plus suggested search
terms. For example, if the user enters 'pizza in new', the pick list may
include the phrase 'pizza in New York, NY' as well as the names of various
pizza outlets. When a user selects a place from the list,
information about that place is returned to the SearchBox object, and can be
retrieved by your application.
The SearchBox
constructor takes two arguments:
- An HTML
input
element of typetext
. This is the input field that theSearchBox
service will monitor and attach its results to. - An
options
argument, which can contain thebounds
property:bounds
is agoogle.maps.LatLngBounds
object specifying the area in which to search for places. The results are biased towards, but not restricted to, places contained within these bounds.
The following code uses the bounds parameter to bias the results towards places within a particular geographic area, specified via laitude/longitude coordinates.
var defaultBounds = new google.maps.LatLngBounds( new google.maps.LatLng(-33.8902, 151.1759), new google.maps.LatLng(-33.8474, 151.2631)); var input = document.getElementById('searchTextField'); var searchBox = new google.maps.places.SearchBox(input, { bounds: defaultBounds });
Changing the search area for SearchBox
To change the search area for an existing SearchBox
, call
setBounds()
on the SearchBox
object and pass the
relevant LatLngBounds
object.
Getting place information
When the user selects an item from the predictions attached to the search
box, the service fires a places_changed
event. You can
call getPlaces()
on the SearchBox
object, to
retrieve an array containing several predictions, each of which is a
PlaceResult
object.
For more information about the PlaceResult
object, refer to
the documentation on
place detail results.
TypeScript
// Listen for the event fired when the user selects a prediction and retrieve // more details for that place. searchBox.addListener("places_changed", () => { const places = searchBox.getPlaces(); if (places.length == 0) { return; } // Clear out the old markers. markers.forEach((marker) => { marker.setMap(null); }); markers = []; // For each place, get the icon, name and location. const bounds = new google.maps.LatLngBounds(); places.forEach((place) => { if (!place.geometry || !place.geometry.location) { console.log("Returned place contains no geometry"); return; } const icon = { url: place.icon as string, size: new google.maps.Size(71, 71), origin: new google.maps.Point(0, 0), anchor: new google.maps.Point(17, 34), scaledSize: new google.maps.Size(25, 25), }; // Create a marker for each place. markers.push( new google.maps.Marker({ map, icon, title: place.name, position: place.geometry.location, }) ); if (place.geometry.viewport) { // Only geocodes have viewport. bounds.union(place.geometry.viewport); } else { bounds.extend(place.geometry.location); } }); map.fitBounds(bounds); });
JavaScript
// Listen for the event fired when the user selects a prediction and retrieve // more details for that place. searchBox.addListener("places_changed", () => { const places = searchBox.getPlaces(); if (places.length == 0) { return; } // Clear out the old markers. markers.forEach((marker) => { marker.setMap(null); }); markers = []; // For each place, get the icon, name and location. const bounds = new google.maps.LatLngBounds(); places.forEach((place) => { if (!place.geometry || !place.geometry.location) { console.log("Returned place contains no geometry"); return; } const icon = { url: place.icon, size: new google.maps.Size(71, 71), origin: new google.maps.Point(0, 0), anchor: new google.maps.Point(17, 34), scaledSize: new google.maps.Size(25, 25), }; // Create a marker for each place. markers.push( new google.maps.Marker({ map, icon, title: place.name, position: place.geometry.location, }), ); if (place.geometry.viewport) { // Only geocodes have viewport. bounds.union(place.geometry.viewport); } else { bounds.extend(place.geometry.location); } }); map.fitBounds(bounds); });
See Styling the Autocomplete and SearchBox widgets to customize the widget appearance.
Programmatically retrieving Place Autocomplete Service predictions
To retrieve predictions programmatically, use the
AutocompleteService
class. AutocompleteService
does not add any UI controls. Instead, it returns an array of prediction
objects, each containing the text of the prediction, reference information,
and details of how the result matches the user input.
This is useful if you want more control over the user interface than is
offered by the Autocomplete
and SearchBox
described above.
AutocompleteService
exposes the following methods:
getPlacePredictions()
returns place predictions. Note: A 'place' can be an establishment, geographic location, or prominent point of interest, as defined by the Places API.getQueryPredictions()
returns an extended list of predictions, which can include places (as defined by the Places API) plus suggested search terms. For example, if the user enters 'pizza in new', the pick list may include the phrase 'pizza in New York, NY' as well as the names of various pizza outlets.
Both of the above methods return an array of prediction objects of the following form:
description
is the matched prediction.distance_meters
is the distance in meters of the place from the specifiedAutocompletionRequest.origin
.matched_substrings
contains a set of substrings in the description that match elements in the user's input. This is useful for highlighting those substrings in your application. In many cases, the query will appear as a substring of the description field.length
is the length of the substring.offset
is the character offset, measured from the beginning of the description string, at which the matched substring appears.
place_id
is a textual identifier that uniquely identifies a place. To retrieve information about the place, pass this identifier in theplaceId
field of a Place Details request. Learn more about how to reference a place with a place ID.terms
is an array containing elements of the query. For a place, each element will typically make up a portion of the address.offset
is the character offset, measured from the beginning of the description string, at which the matched substring appears.value
is the matching term.
The example below executes a query prediction request for the phrase 'pizza near' and displays the result in a list.
TypeScript
// This example retrieves autocomplete predictions programmatically from the // autocomplete service, and displays them as an HTML list. // This example requires the Places library. Include the libraries=places // parameter when you first load the API. For example: // <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places"> function initService(): void { const displaySuggestions = function ( predictions: google.maps.places.QueryAutocompletePrediction[] | null, status: google.maps.places.PlacesServiceStatus ) { if (status != google.maps.places.PlacesServiceStatus.OK || !predictions) { alert(status); return; } predictions.forEach((prediction) => { const li = document.createElement("li"); li.appendChild(document.createTextNode(prediction.description)); (document.getElementById("results") as HTMLUListElement).appendChild(li); }); }; const service = new google.maps.places.AutocompleteService(); service.getQueryPredictions({ input: "pizza near Syd" }, displaySuggestions); } declare global { interface Window { initService: () => void; } } window.initService = initService;
JavaScript
// This example retrieves autocomplete predictions programmatically from the // autocomplete service, and displays them as an HTML list. // This example requires the Places library. Include the libraries=places // parameter when you first load the API. For example: // <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places"> function initService() { const displaySuggestions = function (predictions, status) { if (status != google.maps.places.PlacesServiceStatus.OK || !predictions) { alert(status); return; } predictions.forEach((prediction) => { const li = document.createElement("li"); li.appendChild(document.createTextNode(prediction.description)); document.getElementById("results").appendChild(li); }); }; const service = new google.maps.places.AutocompleteService(); service.getQueryPredictions({ input: "pizza near Syd" }, displaySuggestions); } window.initService = initService;
CSS
HTML
<html> <head> <title>Retrieving Autocomplete Predictions</title> <link rel="stylesheet" type="text/css" href="./style.css" /> <script type="module" src="./index.js"></script> </head> <body> <p>Query suggestions for 'pizza near Syd':</p> <ul id="results"></ul> <!-- Replace Powered By Google image src with self hosted image. https://developers.google.com/maps/documentation/places/web-service/policies#other_attribution_requirements --> <img class="powered-by-google" src="https://storage.googleapis.com/geo-devrel-public-buckets/powered_by_google_on_white.png" alt="Powered by Google" /> <!-- The `defer` attribute causes the script to execute after the full HTML document has been parsed. For non-blocking uses, avoiding race conditions, and consistent behavior across browsers, consider loading using Promises. See https://developers.google.com/maps/documentation/javascript/load-maps-js-api for more information. --> <script src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initService&libraries=places&v=weekly" defer ></script> </body> </html>
Try Sample
Session tokens
AutocompleteService.getPlacePredictions()
can use session tokens (if implemented) to group together autocomplete requests for billing
purposes. Session tokens group the query and selection phases of a user
autocomplete search into a discrete session for billing purposes. The session
begins when the user starts typing a query, and concludes when they select a
place. Each session can have multiple queries, followed by one place selection.
Once a session has concluded, the token is no longer valid. Your app must
generate a fresh token for each session. We recommend using session tokens for
all autocomplete sessions. If the sessionToken
parameter is
omitted, or if you reuse a session token, the session is charged as if no
session token was provided (each request is billed separately).
You can use the same session token to make a single
Place Details
request on the place that results from a call to AutocompleteService.getPlacePredictions()
.
In this case, the autocomplete request is combined with the Place Details
request, and the call is charged as a regular Place Details request. There is no charge for the
autocomplete request.
Be sure to pass a unique session token for each new session. Using the same token for more than one Autocomplete session will invalidate those Autocomplete sessions, and all Autocomplete request in the invalid sessions will be charged individually using Autocomplete Per Request SKU. Read more about session tokens.
The following example shows creating a session token, then passing it in an
AutocompleteService
(the displaySuggestions()
function has been omitted for brevity):
// Create a new session token. var sessionToken = new google.maps.places.AutocompleteSessionToken(); // Pass the token to the autocomplete service. var autocompleteService = new google.maps.places.AutocompleteService(); autocompleteService.getPlacePredictions({ input: 'pizza near Syd', sessionToken: sessionToken }, displaySuggestions);
Be sure to pass a unique session token for each new session. Using the same token for more than one session will result in each request being billed individually.
Read more about session tokens.
Styling the Autocomplete and SearchBox widgets
By default, the UI elements provided by Autocomplete
and
SearchBox
are styled for inclusion on a Google map. You may want
to adjust the styling to suit your own site. The following CSS classes are
available. All classes listed below apply to both the
Autocomplete
and the SearchBox
widgets.
![A graphical illustration of the CSS classes for the Autocomplete and
SearchBox widgets](/https/developers.google.com/static/maps/documentation/javascript/images/place-autocomplete-css-diagram.png)
CSS class | Description |
---|---|
pac-container |
The visual element containing the list of predictions returned by the
Place Autocomplete service. This list appears as a dropdown list below the
Autocomplete or SearchBox widget. |
pac-icon |
The icon displayed to the left of each item in the list of predictions. |
pac-item |
An item in the list of predictions supplied by the
Autocomplete or SearchBox widget. |
pac-item:hover |
The item when the user hovers their mouse pointer over it. |
pac-item-selected |
The item when the user selects it via the keyboard. Note: Selected items
will be a member of this class and of the pac-item class.
|
pac-item-query |
A span inside a pac-item that is the main part of the
prediction. For geographic locations, this contains a place name, like
'Sydney', or a street name and number, like '10 King Street'. For
text-based searches such as 'pizza in New York', it contains the full text
of the query. By default, the pac-item-query is colored
black. If there is any additional text in the pac-item , it is
outside pac-item-query and inherits its styling from
pac-item . It is colored gray by default. The additional text
is typically an address. |
pac-matched |
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 pac-item . It is not
necessarily part of pac-item-query , and it could be partly
within pac-item-query as well as partly in the remaining text
in pac-item . |
Use the Place Picker component
Note: This sample uses an open source library. See the README for support and feedback related to the library.
Try web components. Use the Place Picker web component to enable text input that allows end users to search for a specific address or place using autocomplete.
![GIF with search box. User starts to type an address as input and a dropdown with related
addresses appears. User clicks an address from the dropdown and the search box fills
in the rest of the address.](/https/developers.google.com/static/maps/documentation/javascript/images/place-picker.gif)
Place Autocomplete optimization
This section describes best practices to help you make the most of the Place Autocomplete service.
Here are some general guidelines:
- The quickest way to develop a working user interface is to use the Maps JavaScript API Autocomplete widget, Places SDK for Android Autocomplete widget, or Places SDK for iOS Autocomplete UI control
- Develop an understanding of essential Place Autocomplete data fields from the start.
- Location biasing and location restriction fields are optional but can have a significant impact on autocomplete performance.
- Use error handling to make sure your app degrades gracefully if the API returns an error.
- Make sure your app handles when there is no selection and offers users a way to continue.
Cost optimization best practices
Basic cost optimization
To optimize the cost of using the Place Autocomplete service, use field masks in Place Details and Place Autocomplete widgets to return only the place data fields you need.
Advanced cost optimization
Consider programmatic implementation of Place Autocomplete in order to access Per Request pricing and request Geocoding API results about the selected place instead of Place Details. Per Request pricing paired with Geocoding API is more cost-effective than Per Session (session-based) pricing if both of the following conditions are met:
- If you only need the latitude/longitude or address of the user's selected place, the Geocoding API delivers this information for less than a Place Details call.
- If users select an autocomplete prediction within an average of four Autocomplete predictions requests or fewer, Per Request pricing may be more cost-effective than Per Session pricing.
Does your application require any information other than the address and latitude/longitude of the selected prediction?
Yes, needs more details
Use session-based Place Autocomplete with Place Details.
Since your application requires Place Details such as the place name, business status, or opening hours, your implementation of Place Autocomplete should use a session token (programmatically or built into the JavaScript, Android, or iOS widgets) for a total cost of $0.017 per session plus applicable Places Data SKUs depending on which place data fields you request.1
Widget implementation
Session management is automatically built into the JavaScript, Android, or iOS widgets. This includes both the Place Autocomplete requests and the Place Details request on the selected prediction. Be sure to specify the fields
parameter in order to ensure you are only requesting the
place data fields you need.
Programmatic implementation
Use a session token with your Place Autocomplete requests. When requesting Place Details about the selected prediction, include the following parameters:
- The place ID from the Place Autocomplete response
- The session token used in the Place Autocomplete request
- The
fields
parameter specifying the place data fields you need
No, needs only address and location
Geocoding API could be a more cost-effective option than Place Details for your application, depending on the performance of your Place Autocomplete usage. Every application's Autocomplete efficiency varies depending on what users are entering, where the application is being used, and whether performance optimization best practices have been implemented.
In order to answer the following question, analyze how many characters a user types on average before selecting a Place Autocomplete prediction in your application.
Do your users select a Place Autocomplete prediction in four or fewer requests, on average?
Yes
Implement Place Autocomplete programmatically without session tokens and call Geocoding API on the selected place prediction.
Geocoding API delivers addresses and latitude/longitude coordinates for $0.005 per request. Making four Place Autocomplete - Per Request requests costs $0.01132 so the total cost of four requests plus a Geocoding API call about the selected place prediction would be $0.01632 which is less than the Per Session Autocomplete price of $0.017 per session.1
Consider employing performance best practices to help your users get the prediction they're looking for in even fewer characters.
No
Use session-based Place Autocomplete with Place Details.
Since the average number of requests you expect to make before a user selects a Place Autocomplete prediction exceeds the cost of Per Session pricing, your implementation of Place Autocomplete should use a session token for both the Place Autocomplete requests and the associated Place Details request for a total cost of $0.017 per session.1
Widget implementation
Session management is automatically built into the JavaScript, Android, or iOS widgets. This includes both the Place Autocomplete requests and the Place Details request on the selected prediction. Be sure to specify the fields
parameter in order to ensure you are only requesting Basic Data fields.
Programmatic implementation
Use a session token with your Place Autocomplete requests. When requesting Place Details about the selected prediction, include the following parameters:
- The place ID from the Place Autocomplete response
- The session token used in the Place Autocomplete request
- The
fields
parameter specifying Basic Data fields such as address and geometry
Consider delaying Place Autocomplete requests
You can employ strategies such as delaying a Place Autocomplete request until the user has typed in the first three or four characters so that your application makes fewer requests. For example, making Place Autocomplete requests for each character after the user has typed the third character means that if the user types seven characters then selects a prediction for which you make one Geocoding API request, the total cost would be $0.01632 (4 * $0.00283 Autocomplete Per Request + $0.005 Geocoding).1
If delaying requests can get your average programmatic request below four, you can follow the guidance for performant Place Autocomplete with Geocoding API implementation. Note that delaying requests can be perceived as latency by the user who might be expecting to see predictions with every new keystroke.
Consider employing performance best practices to help your users get the prediction they're looking for in fewer characters.
-
Costs listed here are in USD. Please refer to the Google Maps Platform Billing page for full pricing information.
Performance best practices
The following guidelines describe ways to optimize Place Autocomplete performance:
- Add country restrictions, location biasing, and (for programmatic implementations) language preference to your Place Autocomplete implementation. Language preference is not needed with widgets since they pick language preferences from the user's browser or mobile device.
- If Place Autocomplete is accompanied by a map, you can bias location by map viewport.
- In situations when a user does not choose one of the Autocomplete predictions, generally
because none of those predictions are the desired result-address, you can re-use the original
user input to attempt to get more relevant results:
- If you expect the user to enter only address information, re-use the original user input in a call to the Geocoding API.
- If you expect the user to enter queries for a specific place by name or address, use a Find Place request. If results are only expected in a specific region, use location biasing.
- Users inputting subpremise addresses in countries where Place Autocomplete support of subpremise addresses is incomplete, e.g. Czechia, Estonia and Lithuania. For example, the Czech address "Stroupežnického 3191/17, Praha" yields a partial prediction in Place Autocomplete.
- Users inputting addresses with road-segment prefixes like "23-30 29th St, Queens" in New York City or "47-380 Kamehameha Hwy, Kaneohe" on the island of Kauai in Hawai'i.
Usage limits and policies
Quotas
For quota and pricing information, see the Usage and Billing documentation for the Places API.
Policies
Use of the Places Library, Maps JavaScript API must be in accordance with the policies described for the Places API.