Usage and billing
Understand primary usage meters and separate backup calls.
The primary API classifies successful requests with X-Geocoding-Outcome:
| Header value | Meaning |
|---|---|
matched | At least one address candidate or autocomplete suggestion remains |
no_match | The valid request returned no address candidates or suggestions |
These outcomes drive separate primary usage meters. Invalid requests and service failures have no billable geocoding classification. A low-confidence primary result is still matched, unless the geocode request sets min_confidence: results below it are dropped, and a request left with none is no_match. The SDKs send their threshold as min_confidence on geocode when backups are configured and both no_results and low_confidence trigger them, so a geocode that falls back for low confidence is metered as no_match. Search and reverse have no min_confidence, so a low-confidence result there is still matched. A request whose candidates are all excluded is no_match.
Use your account portal and applicable plan for current pricing, allowances, and limits. The SDK does not expose the primary metering header in its normalized response.
All primary operations (geocode, search, reverse, autocomplete, and place lookup) are metered, including requests made with public browser tokens. Primary autocomplete already returns full results, so a separate lookup is only needed for ids you stored earlier. Debounce input to avoid unnecessary searches. CORS preflight (OPTIONS) requests are not metered. Origin-denied requests are service errors with no billable classification.
Backups are separate calls
Each Google or HERE call uses your own provider credentials and quota. A single SDK operation may call primary and multiple backups. An international hint can skip primary and use only backups. Fallback attempts are not merged into the primary API's usage classification.
A per-client fallback budget limits backup calls made by geocode, reverse geocode, and autocomplete, including failed and empty responses. Google Place Details and HERE lookup calls made during selection resolution are separate provider calls and are outside the SDK fallback budget and circuit breaker. The budget does not track money, shared account usage, or calls from other clients. A new client or process resets it; PHP request lifetimes often reset it on every incoming request.
Configure provider account quotas for an aggregate limit. Use fallback budgets and circuit breakers, and inspect attempts to understand which providers were called or skipped.