Using session tokens
Session tokens group the query and selection phases of a user autocompletesearch into a discrete session for billing purposes. The following examples showhow to use session tokens in Autocomplete (New) and Place Details (New) calls.
Create a session token
Users are responsible for generating unique session tokens for each session.Google recommends usingversion 4 UUIDs.
Note: Session tokens can overlap across Google Cloud Console projects, but theymust be unique per project. For example, an app using Project A and an app usingProject B can use the same session token, but multiple apps using Project Acannot use the same session token.Make an Autocomplete (New) request
An Autocomplete (New) request is an HTTP POST request. For moreinformation about request body parameters, seeAutocomplete (New)requests.
The following series of requests show a user searching for a pizza shop in SanFrancisco. As the user begins typing a query, Autocomplete (New) is calledfor each keystroke. The generated session token is passed as a parameter in eachcall.
First request and response
Request 1
curl -X POST -d '{ "input": "p", "sessionToken": "3519edfe-0f75-4a30-bfe4-7cbd89340b2c", "locationBias": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 500.0 } }}' -H 'Content-Type: application/json' -H "X-Goog-Api-Key:YOUR_API_KEY" \https://places.googleapis.com/v1/places:autocompleteResponse 1
{"suggestions":[{"placePrediction":{"place":"places/ChIJHSGzi_yAhYARnrPmDWAx9ro","placeId":"ChIJHSGzi_yAhYARnrPmDWAx9ro","text":{"text":"PIER 39, The Embarcadero, San Francisco, CA, USA","matches":[{"endOffset":1}]},"structuredFormat":{"mainText":{"text":"PIER 39","matches":[{"endOffset":1}]},"secondaryText":{"text":"The Embarcadero, San Francisco, CA, USA"}},"types":["historical_landmark","shopping_mall","point_of_interest","establishment","marina","tourist_attraction"]}},]/.../}
Second request and response
Request 2
curl -X POST -d '{ "input": "pi", "sessionToken": "3519edfe-0f75-4a30-bfe4-7cbd89340b2c", "locationBias": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 500.0 } }}' -H 'Content-Type: application/json' -H "X-Goog-Api-Key:YOUR_API_KEY" \https://places.googleapis.com/v1/places:autocompleteResponse 2
{"suggestions":[{"placePrediction":{"place":"places/ChIJHSGzi_yAhYARnrPmDWAx9ro","placeId":"ChIJHSGzi_yAhYARnrPmDWAx9ro","text":{"text":"PIER 39, The Embarcadero, San Francisco, CA, USA","matches":[{"endOffset":2}]},"structuredFormat":{"mainText":{"text":"PIER 39","matches":[{"endOffset":2}]},"secondaryText":{"text":"The Embarcadero, San Francisco, CA, USA"}},"types":["establishment","point_of_interest","shopping_mall","marina","historical_landmark","tourist_attraction"]}},/.../]}
Third request and response
Request 3
curl -X POST -d '{ "input": "piz", "sessionToken": "3519edfe-0f75-4a30-bfe4-7cbd89340b2c", "locationBias": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 500.0 } }}' -H 'Content-Type: application/json' -H "X-Goog-Api-Key:YOUR_API_KEY" https://places.googleapis.com/v1/places:autocompleteResponse 3
{"suggestions":[{"placePrediction":{"place":"places/ChIJ_QJSSfGAhYARQVFJBNKy3HE","placeId":"ChIJ_QJSSfGAhYARQVFJBNKy3HE","text":{"text":"Pizza By The Slice, Grant Avenue, San Francisco, CA, USA","matches":[{"endOffset":3}]},"structuredFormat":{"mainText":{"text":"Pizza By The Slice","matches":[{"endOffset":3}]},"secondaryText":{"text":"Grant Avenue, San Francisco, CA, USA"}},"types":["establishment","point_of_interest","food","pizza_restaurant","restaurant"]}},/.../]}
inputOffset parameter to specify the positionof the cursor in the input field.End the session
Terminate a session by making a request to Place Details (New) or AddressValidation and passing the same session token that you used for the Autocomplete(New) requests.
Make a Place Details (New) request
A Place Details (New) request is an HTTP GET request. For more informationabout request body parameters, seePlace Details (New) requests.
The following Place Details (New) request includes the selected place'sid and thesessionToken used in previous Autocomplete (New) calls.
curl -X GET -H 'Content-Type: application/json' \-H "X-Goog-Api-Key:YOUR_API_KEY" \-H "X-Goog-FieldMask: id,displayName,accessibilityOptions,businessStatus" \https://places.googleapis.com/v1/places/ChIJ_QJSSfGAhYARQVFJBNKy3HE?sessionToken=3519edfe-0f75-4a30-bfe4-7cbd89340b2c
Using a placeid ofChIJ_QJSSfGAhYARQVFJBNKy3HE, the call generates thefollowing JSON response:
{"id":"ChIJ_QJSSfGAhYARQVFJBNKy3HE","businessStatus":"OPERATIONAL","displayName":{"text":"Pizza By The Slice","languageCode":"en"},"accessibilityOptions":{"wheelchairAccessibleParking":false,"wheelchairAccessibleEntrance":true}}
Make an Address Validation request
An Address Validation request is an HTTP POST request. For more informationabout request body parameters, seeSend an address validation request.
The following Address Validation request includes the address of the selectedplace, found in thetext field of the Autocomplete (New) response, and thesessionToken used in previous Autocomplete (New) calls. curl -X POST -d '{ "sessionToken": "3519edfe-0f75-4a30-bfe4-7cbd89340b2c", "address": { "addressLines": "Pizza By The Slice, Grant Avenue, San Francisco, CA, USA" } }' \ -H 'Content-Type: application/json' \ "https://addressvalidation.googleapis.com/v1:validateAddress?key=YOUR_API_KEY"The call generates the following JSON response:
{"result":{"verdict":{"inputGranularity":"PREMISE","validationGranularity":"PREMISE","geocodeGranularity":"PREMISE","hasInferredComponents":true},"address":{"formattedAddress":"Pizza By The Slice, Grant Avenue, San Francisco, CA 94133, USA","postalAddress":{"regionCode":"US","languageCode":"en","postalCode":"94133","administrativeArea":"CA","locality":"San Francisco","addressLines":["Pizza By The Slice","Grant Ave"]},"addressComponents":[{"componentName":{"text":"Pizza By The Slice","languageCode":"en"},"componentType":"point_of_interest","confirmationLevel":"CONFIRMED"},{"componentName":{"text":"Grant Avenue","languageCode":"en"},"componentType":"route","confirmationLevel":"CONFIRMED"},{"componentName":{"text":"San Francisco","languageCode":"en"},"componentType":"locality","confirmationLevel":"CONFIRMED"},{"componentName":{"text":"CA","languageCode":"en"},"componentType":"administrative_area_level_1","confirmationLevel":"CONFIRMED"},{"componentName":{"text":"USA","languageCode":"en"},"componentType":"country","confirmationLevel":"CONFIRMED"},{"componentName":{"text":"94133"},"componentType":"postal_code","confirmationLevel":"CONFIRMED","inferred":true}],"missingComponentTypes":["street_number"]},"geocode":{"location":{"latitude":37.800504,"longitude":-122.4074794},"plusCode":{"globalCode":"849VRH2V+62"},"bounds":{"low":{"latitude":37.800504,"longitude":-122.4074794},"high":{"latitude":37.800504,"longitude":-122.4074794}},"featureSizeMeters":10,"placeId":"ChIJ_QJSSfGAhYARQVFJBNKy3HE","placeTypes":["food","restaurant","point_of_interest","establishment"]},"uspsData":{"standardizedAddress":{"firstAddressLine":"PIZZA BY THE SLICE","secondAddressLine":"GRANT AVE","cityStateZipAddressLine":"SAN FRANCISCO","city":"SAN FRANCISCO","state":"CA","zipCode":"94133"},"dpvFootnote":"A1M1","postOfficeCity":"SAN FRANCISCO","postOfficeState":"CA"}},"responseId":"4b669675-2c3b-463a-ae20-400248cf6ac9"}
Abandon a session
A session terminates if the user abandons the session. For example, if a userbegins searching for a pizza shop but does not select a place (triggering aPlace Details (New) call) or validate the address (triggering an AddressValidation call), the session terminates and the session token expires.
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.