Address autocomplete
Present country-restricted suggestions and resolve the selected result.
Call autocomplete while the user types a partial address, display the returned labels, and keep each suggestion's provider and identifier. Call resolveAutocomplete (Node.js/PHP) or resolve_autocomplete (Python) with the selected suggestion to obtain the complete address and coordinates. Over HTTP, primary autocomplete returns full results directly and GET /v1/place looks a result up again by id.
All SDKs require q and country. The primary service handles CA, US, and MX. An explicit country outside these routes to configured Google Places Autocomplete (New) or HERE Address Autocomplete providers in order. Empty suggestions, timeouts, network errors, and primary HTTP 5xx may trigger fallback according to fallbackOn/fallback_on. Partial addresses do not use confidence scoring. Fallback budgets and circuit breakers are shared with geocoding calls on the same client.
Use limit (1–10, default 5), optional near (lat/lon) for location bias, and exclude_sources for primary records. The provider response is included when a fallback wins. Google suggestions carry a session token; pass the suggestion object unchanged to resolution so Place Details (New) uses the same token. Supply sessionToken in Node.js/PHP or session_token in Python across successive keystrokes of one Google session; otherwise each autocomplete call generates a new token. A selection resolves through primary place lookup (GET /v1/place), Google Place Details (New), or HERE lookup according to its provider.
The selected result has the usual normalized fields: id, label, type, house number, street, city, state, ZIP, country code, coordinates, source, and provider. Google and HERE scores are not used to rank partial address suggestions. Resolution raises a provider error if the selected ID no longer resolves. Client cancellation and timeouts apply to both methods.
Resolution behavior
Resolution returns one GeocodingResult, rather than an envelope containing results, attempts, or raw provider metadata. It calls only the selected suggestion's provider. Google/HERE must still be configured on the resolving server client. It does not run fallbacks, reserve fallback budget, or check/update circuit breakers; use provider account quotas for aggregate spending limits.
A primary HTTP lookup with no match returns HTTP 200 and an empty features array. Server and browser SDKs turn that empty lookup into GeocodingError with provider_error. Resolution failures have no provider-chain attempt history. An empty autocomplete list, by contrast, remains a successful empty suggestion response after eligible fallback processing.
sessionToken / session_token is SDK-only and is omitted from primary HTTP bodies. Google suggestions retain it for Place Details; primary and HERE suggestions do not include it. exclude_sources filters primary suggestions but is not an option on resolution. Autocomplete and a subsequent primary lookup are separate metered requests; each successful keystroke search can add usage. See usage and billing.
Public browser tokens
Use the browser autocomplete client in any frontend library. Workspace admins create pub_ tokens with 1–20 exact allowed origins in the account portal. They work only on GET /v1/autocomplete and GET /v1/place, and require an allowed Origin plus the token in the apikey header. Missing or unlisted origins and other operations return HTTP 403. CORS preflight requests do not need credentials; authenticated requests still enforce the allow-list. Bare domains mean HTTPS; list each subdomain and development port separately. No wildcard domains are accepted.
Tokens are public and requests still count toward your rate limits and billing. Non-browser callers can forge Origin headers, so domain restrictions do not make tokens secret. Keep backend credentials on the server. Optional browser Google/HERE fallbacks use separate public, website-restricted provider keys configured in the SDK; they are sent directly to providers. No JSON request fields change.
For .NET, use the C# client. Its async methods accept CancellationToken; reuse a client to share backup budgets and circuit state.