The Place Autocomplete Data API lets you fetch place predictions programmatically, to create customized autocomplete experiences with a finer degree of control than is possible with the autocomplete widget. In this guide you will learn how to use the Place Autocomplete Data API to make autocomplete requests based on user queries.
The following example shows a simplified type-ahead integration. Enter your search query, such as "pizza" or "poke", then click to select the result you want.
Autocomplete requests
An autocomplete request takes a query input string and returns a list of place predictions. To
make an autocomplete request, call fetchAutocompleteSuggestions()
and pass a request with the needed properties. The input
property contains the string to search; in a typical application this value would be updated as
the user types a query. The request should include a sessionToken
,
which is used for billing purposes.
The following snippet shows creating a request body and adding a session token, then calling fetchAutocompleteSuggestions()
to get a list of PlacePrediction
s.
// Add an initial request body. let request = { input : "Tadi" , locationRestriction : { west : - 122.44 , north : 37.8 , east : - 122.39 , south : 37.78 , }, origin : { lat : 37.7893 , lng : - 122.4039 }, includedPrimaryTypes : [ "restaurant" ], language : "en-US" , region : "us" , }; // Create a session token. const token = new AutocompleteSessionToken (); // Add the token to the request. // @ts-ignore request . sessionToken = token ;
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 Place Autocomplete options 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.
Use the origin
property to specify the origin point from which to calculate
geodesic distance to the destination. If this value is omitted, distance is not returned.
Use the includedPrimaryTypes
property to specify up to five place types
.
If no types are specified, places of all types will be returned.
Get place details
To return a Place
object from a place prediction result, first call toPlace()
,
then call fetchFields()
on the resulting Place
object (the session ID from the place prediction is automatically included). Calling fetchFields()
ends the
autocomplete session.
let place = suggestions [ 0 ]. placePrediction . toPlace (); // Get first predicted place. await place . fetchFields ({ fields : [ "displayName" , "formattedAddress" ], }); const placeInfo = document . getElementById ( "prediction" ); placeInfo . textContent = "First predicted place: " + place . displayName + ": " + place . formattedAddress ;
Session tokens
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. The session is concluded when the user selects a place and a call to Place Details is made.
To create a new session token and add it to a request, create an instance of AutocompleteSessionToken
,
then set the sessionToken
property of the request to use the tokens as shown in the following snippet:
// Create a session token. const token = new AutocompleteSessionToken (); // Add the token to the request. // @ts-ignore request . sessionToken = token ;
A session is concluded when fetchFields()
is called. After creating the Place
instance, you don't need to pass the session
token to fetchFields()
as this is handled automatically.
await place . fetchFields ({ fields : [ "displayName" , "formattedAddress" ], });
Make a session token for the next session by creating a new instance of AutocompleteSessionToken
.
Session token recommendations:
- Use session tokens for all Place Autocomplete calls.
- Generate a fresh token for each session.
- 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.
You can optionally omit the autocomplete session token from a request. If the session token is omitted, each request is billed separately, triggering the Autocomplete - Per Request SKU. If you reuse a session token, the session is considered invalid and the requests are charged as if no session token was provided.
Example
As the user types a query, an autocomplete request is called every few keystrokes (not per-character), and a list of possible results is returned. When the user makes a selection from the result list, the selection counts as a request, and all of the requests made during the search are bundled and counted as a single request. If the user selects a place, the search query is available at no charge, and only the Place data request is charged. If the user does not make a selection within a few minutes of the beginning of the session, only the search query is charged.
From the perspective of an app, the flow of events goes like this:
- A user begins typing a query to search for "Paris, France".
- Upon detecting user input, the app creates a new session token, "Token A".
- As the user types, the API makes an autocomplete request every few
characters, displaying a new list of potential results for each:
"P"
"Par"
"Paris,"
"Paris, Fr" - When the user makes a selection:
- All requests resulting from the query are grouped and added to the session represented by "Token A", as a single request.
- The user's selection is counted as a Place Detail request, and added to the session represented by "Token A".
- The session is concluded, and the app discards "Token A".
Complete example code
This section contains complete examples showing how to use the Place Autocomplete Data API .Place autocomplete predictions
The following example demonstrates calling fetchAutocompleteSuggestions()
for the input "Tadi", then calling toPlace()
on the first prediction result, followed by a call to fetchFields()
to get place details.
TypeScript
/** * Demonstrates making a single request for Place predictions, then requests Place Details for the first result. */ async function init () { // @ts-ignore const { Place , AutocompleteSessionToken , AutocompleteSuggestion } = await google . maps . importLibrary ( "places" ) as google . maps . PlacesLibrary ; // Add an initial request body. let request = { input : "Tadi" , locationRestriction : { west : - 122.44 , north : 37.8 , east : - 122.39 , south : 37.78 }, origin : { lat : 37.7893 , lng : - 122.4039 }, includedPrimaryTypes : [ "restaurant" ], language : "en-US" , region : "us" , }; // Create a session token. const token = new AutocompleteSessionToken (); // Add the token to the request. // @ts-ignore request . sessionToken = token ; // Fetch autocomplete suggestions. const { suggestions } = await AutocompleteSuggestion . fetchAutocompleteSuggestions ( request ); const title = document . getElementById ( 'title' ) as HTMLElement ; title . appendChild ( document . createTextNode ( 'Query predictions for "' + request . input + '":' )); for ( let suggestion of suggestions ) { const placePrediction = suggestion . placePrediction ; // Create a new list element. const listItem = document . createElement ( 'li' ); const resultsElement = document . getElementById ( "results" ) as HTMLElement ; listItem . appendChild ( document . createTextNode ( placePrediction . text . toString ())); resultsElement . appendChild ( listItem ); } let place = suggestions [ 0 ]. placePrediction . toPlace (); // Get first predicted place. await place . fetchFields ({ fields : [ 'displayName' , 'formattedAddress' ], }); const placeInfo = document . getElementById ( "prediction" ) as HTMLElement ; placeInfo . textContent = 'First predicted place: ' + place . displayName + ': ' + place . formattedAddress ; } init ();
JavaScript
/** * Demonstrates making a single request for Place predictions, then requests Place Details for the first result. */ async function init () { // @ts-ignore const { Place , AutocompleteSessionToken , AutocompleteSuggestion } = await google . maps . importLibrary ( "places" ); // Add an initial request body. let request = { input : "Tadi" , locationRestriction : { west : - 122.44 , north : 37.8 , east : - 122.39 , south : 37.78 , }, origin : { lat : 37.7893 , lng : - 122.4039 }, includedPrimaryTypes : [ "restaurant" ], language : "en-US" , region : "us" , }; // Create a session token. const token = new AutocompleteSessionToken (); // Add the token to the request. // @ts-ignore request . sessionToken = token ; // Fetch autocomplete suggestions. const { suggestions } = await AutocompleteSuggestion . fetchAutocompleteSuggestions ( request ); const title = document . getElementById ( "title" ); title . appendChild ( document . createTextNode ( 'Query predictions for "' + request . input + '":' ), ); for ( let suggestion of suggestions ) { const placePrediction = suggestion . placePrediction ; // Create a new list element. const listItem = document . createElement ( "li" ); const resultsElement = document . getElementById ( "results" ); listItem . appendChild ( document . createTextNode ( placePrediction . text . toString ()), ); resultsElement . appendChild ( listItem ); } let place = suggestions [ 0 ]. placePrediction . toPlace (); // Get first predicted place. await place . fetchFields ({ fields : [ "displayName" , "formattedAddress" ], }); const placeInfo = document . getElementById ( "prediction" ); placeInfo . textContent = "First predicted place: " + place . displayName + ": " + place . formattedAddress ; } init ();
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 ; }
HTML
<html> <head> <title>Place Autocomplete Data API Predictions</title> <link rel="stylesheet" type="text/css" href="./style.css" /> <script type="module" src="./index.js"></script> </head> <body> <div id="title"></div> <ul id="results"></ul> <p><span id="prediction"></span></p> <img class="powered-by-google" src="https://storage.googleapis.com/geo-devrel-public-buckets/powered_by_google_on_white.png" alt="Powered by Google" /> <!-- 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: "AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg", v: "weekly"});</script> </body> </html>
Try Sample
Place autocomplete type-ahead with sessions
This example demonstrates calling fetchAutocompleteSuggestions()
based on user queries, showing a list of predicted places in response, and finally retrieving
place details for the selected place. The example also demonstrates the use of session tokens to
group a user query with the final Place Details request.
TypeScript
let titleElement ; let resultsContainerElement ; let inputElement ; let newestRequestId = 0 ; // Add an initial request body. const request = { input : '' , locationRestriction : { west : - 122.44 , north : 37.8 , east : - 122.39 , south : 37.78 }, origin : { lat : 37.7893 , lng : - 122.4039 }, includedPrimaryTypes : [ 'restaurant' ], language : 'en-US' , region : 'us' , }; function init () { titleElement = document . getElementById ( 'title' ); resultsContainerElement = document . getElementById ( 'results' ); inputElement = document . querySelector ( 'input' ); inputElement . addEventListener ( 'input' , makeAutocompleteRequest ); refreshToken ( request ); } async function makeAutocompleteRequest ( inputEvent ) { // Reset elements and exit if an empty string is received. if ( inputEvent . target . value == '' ) { titleElement . innerText = '' ; resultsContainerElement . replaceChildren (); return ; } // Add the latest char sequence to the request. request . input = inputEvent . target . value ; // To avoid race conditions, store the request ID and compare after the request. const requestId = ++ newestRequestId ; // Fetch autocomplete suggestions and show them in a list. // @ts-ignore const { suggestions } = await google . maps . places . AutocompleteSuggestion . fetchAutocompleteSuggestions ( request ); // If the request has been superseded by a newer request, do not render the output. if ( requestId !== newestRequestId ) return ; titleElement . innerText = `Query predictions for " ${ request . input } "` ; // Clear the list first. resultsContainerElement . replaceChildren (); for ( const suggestion of suggestions ) { const placePrediction = suggestion . placePrediction ; // Create a link for the place, add an event handler to fetch the place. const a = document . createElement ( 'a' ); a . addEventListener ( 'click' , () = > { onPlaceSelected ( placePrediction ! . toPlace ()); }); a . innerText = placePrediction ! . text . toString (); // Create a new list item element. const li = document . createElement ( 'li' ); li . appendChild ( a ); resultsContainerElement . appendChild ( li ); } } // Event handler for clicking on a suggested place. async function onPlaceSelected ( place ) { await place . fetchFields ({ fields : [ 'displayName' , 'formattedAddress' ], }); const placeText = document . createTextNode ( ` ${ place . displayName } : ${ place . formattedAddress } ` ); resultsContainerElement . replaceChildren ( placeText ); titleElement . innerText = 'Selected Place:' ; inputElement . value = '' ; refreshToken ( request ); } // Helper function to refresh the session token. function refreshToken ( request ) { // Create a new session token and add it to the request. request . sessionToken = new google . maps . places . AutocompleteSessionToken (); } declare global { interface Window { init : () = > void ; } } window . init = init ;
JavaScript
let titleElement ; let resultsContainerElement ; let inputElement ; let newestRequestId = 0 ; // Add an initial request body. const request = { input : '' , locationRestriction : { west : - 122.44 , north : 37.8 , east : - 122.39 , south : 37.78 }, origin : { lat : 37.7893 , lng : - 122.4039 }, includedPrimaryTypes : [ 'restaurant' ], language : 'en-US' , region : 'us' , }; function init () { titleElement = document . getElementById ( 'title' ); resultsContainerElement = document . getElementById ( 'results' ); inputElement = document . querySelector ( 'input' ); inputElement . addEventListener ( 'input' , makeAutocompleteRequest ); refreshToken ( request ); } async function makeAutocompleteRequest ( inputEvent ) { // Reset elements and exit if an empty string is received. if ( inputEvent . target . value == '' ) { titleElement . innerText = '' ; resultsContainerElement . replaceChildren (); return ; } // Add the latest char sequence to the request. request . input = inputEvent . target . value ; // To avoid race conditions, store the request ID and compare after the request. const requestId = ++ newestRequestId ; // Fetch autocomplete suggestions and show them in a list. // @ts-ignore const { suggestions } = await google . maps . places . AutocompleteSuggestion . fetchAutocompleteSuggestions ( request ); // If the request has been superseded by a newer request, do not render the output. if ( requestId !== newestRequestId ) return ; titleElement . innerText = `Query predictions for " ${ request . input } "` ; // Clear the list first. resultsContainerElement . replaceChildren (); for ( const suggestion of suggestions ) { const placePrediction = suggestion . placePrediction ; // Create a link for the place, add an event handler to fetch the place. const a = document . createElement ( 'a' ); a . addEventListener ( 'click' , () = > { onPlaceSelected ( placePrediction . toPlace ()); }); a . innerText = placePrediction . text . toString (); // Create a new list item element. const li = document . createElement ( 'li' ); li . appendChild ( a ); resultsContainerElement . appendChild ( li ); } } // Event handler for clicking on a suggested place. async function onPlaceSelected ( place ) { await place . fetchFields ({ fields : [ 'displayName' , 'formattedAddress' ], }); const placeText = document . createTextNode ( ` ${ place . displayName } : ${ place . formattedAddress } ` ); resultsContainerElement . replaceChildren ( placeText ); titleElement . innerText = 'Selected Place:' ; inputElement . value = '' ; refreshToken ( request ); } // Helper function to refresh the session token. function refreshToken ( request ) { // Create a new session token and add it to the request. request . sessionToken = new google . maps . places . AutocompleteSessionToken (); } window . init = init ;
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 ; } a { cursor : pointer ; text-decoration : underline ; color : blue ; } input { width : 300 px ; }
HTML
<html> <head> <title>Place Autocomplete Data API Session</title> <link rel="stylesheet" type="text/css" href="./style.css" /> <script type="module" src="./index.js"></script> </head> <body> <input id="input" type="text" placeholder="Search for a place..." /> <div id="title"></div> <ul id="results"></ul> <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=AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8&callback=init&libraries=places&v=weekly" defer ></script> </body> </html>
