Sessions (v2 Autocomplete Billing)

The v2 autocomplete API bills by session, not by request. Understanding how a session starts, continues, and ends is essential to avoid unexpectedly high usage.

How it Works

• The billable unit is a session start, not each individual keystroke.
• Pass one stable session_token across every autocomplete request that belongs to the same user search. A run of keystrokes sharing a token is one session.
• A session ends — and the next request starts a new one — on any of:
  • a /v2/retrieve/ call, which closes the session;
  • 50 suggest calls sharing a token (the roll to a new session happens on request 51);
  • 2 minutes of idle time with no request on that token.

Omitting session_token costs roughly 5x

If you omit session_token, a fresh session is minted for every request. Each keystroke then bills as its own session instead of one session covering the whole search — in practice this multiplies cost by roughly 5x for a typical search. Always pass a session_token.

Three retrieves in a row is three sessions

Each /v2/retrieve/ call closes the session it belongs to. If you call retrieve three times in a row on the same token — for example to try resolving several candidates — that is three separate sessions, not one, because each retrieve both starts (if none was already open) and closes a session.

Recommendations

• Debounce input by roughly 150ms before firing an autocomplete request, to avoid burning through the 50-request cap on fast typists.
• Reuse the same session_token for the full lifetime of one search box interaction, from the first keystroke until the user picks a result or abandons the search.
• Generate a new session_token only when the user starts a genuinely new search (e.g. clears the box, or 2 minutes have passed).

Worked Example

A user types "Nieuwezijds" into a search box, one character at a time, with a single session_token (sess_a1b2c3) attached to every request:

1. q=v → autocomplete call, session_token=sess_a1b2c3
2. q=vo → autocomplete call, same token
3. q=vog → autocomplete call, same token
4. q=voge → autocomplete call, same token
5. q=vogel → autocomplete call, same token
6. q=Nieuwezijds → autocomplete call, same token

That's 6 suggest calls sharing one token. The user then picks Nieuwezijds Voorburgwal 147, Maastricht from the suggestion list, and the client calls:

7. /v2/retrieve/?ord=128371&country=nl&layer=address&session_token=sess_a1b2c3

The retrieve call closes the session.

Total: one billable session, regardless of the 6 keystrokes that led up to it.

See Also

• Autocomplete — where session_token is attached to each suggest request.
• Retrieve — where a session is closed.