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 and a call to Place Details is made. If the user does not make a selection, the session will end after a short time out period. 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.
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 Character 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 free, 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.
Let's examine this flow of events from the perspective of an app.
- 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".
For more information about how Autocomplete requests are billed, see Usage and Billing.
Create session tokens
To create a session token, call
AutocompleteSessionToken.newInstance()
.