Session Tokens

Autocomplete uses session tokens to group the user's query and the user's selected result into a discrete session for billing purposes.

An Autocomplete session begins when the user starts typing a query, and concludes when they select a result and a call is made to Place Search, Place Details, or Address Details.

Each Autocomplete session can have multiple user queries, capped by the result selection. The API token used for each request within a session must belong to the same Project. Once a session has concluded, the session token is no longer valid; your project must generate a fresh token for each session.

If the session_token parameter is omitted, the session is charged per keystroke/request.

Recommended Usage Guidelines

  • Use session tokens for all autocomplete sessions.
  • Generate a new token for each session. Be sure to pass a unique session token for each new session.
  • Ensure that the same API token is used for all Autocomplete and followup endpoint requests within a session.

You can optionally decline to use session_token. If the session token is omitted, each Autocomplete request is billed separately (per keystroke). If you reuse a session_token, then the session is treated as a fresh user session.


A walkthrough of the experience for a user searching for and selecting their desired result.

  1. A user begins typing a query to search for "Majordomo".

  2. Upon detecting user input, the app creates a new session token, "Token ABC".

  3. As the user types, the API makes an autocomplete request per character and refreshes the displayed list of suggested results:

  4. When the user sees their preferred result, they will make a selection:

    • All Autocomplete requests are grouped and added to the session represented by "Token ABC", and are considered free API calls.
    • The user's selection "Majordomo" is counted as a call to the Place Details endpoint, and added to the session represented by "Token ABC". The charge for this API call remains.
  5. The session is concluded and "Token ABC" gets discarded.

Creating Session Tokens

You can create and pass through any randomized session token, so long as it is Alphanumeric (ABC123) and 32 characters long. We recommend you auto-generate and auto-assign session tokens in a programmatic fashion.