Guides

Provider fallbacks

Configure Google and HERE, selection rules, and backup limits.

Fallbacks run in the SDK on your backend. The HTTP service does not call Google or HERE. No backups are enabled by default; configure provider keys to enable them.

Geocode and reverse-geocode selection

1. Use country routing to select primary first or skip directly to backups.
2. Keep primary results if any candidate meets the confidence threshold, which defaults to 0.8. Candidate order stays unchanged.
3. If primary returns no results, all primary scores are below the threshold, or primary has an eligible outage, try configured backups sequentially.
4. Return the first nonempty backup response. Backup scores are not tested against the primary threshold.
5. If all backups fail, return the original primary results, including an empty list. If primary failed, raise its original error with the complete attempt history. Unsupported-country exhaustion raises unsupported_country.

The default triggers are no_results, low_confidence, timeout, network, and server_error. server_error means primary HTTP 500–599. HTTP 4xx, malformed primary responses, caller cancellation, and total deadline expiration do not trigger fallback.

fallbackOn in TypeScript/PHP and fallback_on in Python replace the default list. Use an empty list to disable triggered fallback, or only no_results and low_confidence to disable outage fallback. International routing still runs independently of this list.

Autocomplete and resolution

Autocomplete uses the same provider order and eligible outage triggers, but accepts a nonempty primary suggestion list without confidence scoring. low_confidence does not apply. It requires a recognized country; unsupported primary countries route directly to backups. If backups are exhausted, the original empty primary suggestion list is returned, or the primary/country-routing error is raised. See autocomplete.

Resolution calls only the selected suggestion's provider. It does not use the selection policy, fallback budget, or circuit breaker, and does not switch providers when a lookup fails.

TypeScript configuration

import { GeocodingClient } from '@affordable-geo-apis/sdk';

const client = new GeocodingClient({
  baseUrl: process.env.GEOCODING_BASE_URL!,
  apiKey: process.env.GEOCODING_API_KEY!,
  confidenceThreshold: 0.8,
  fallbackOn: ['no_results', 'low_confidence', 'timeout', 'network', 'server_error'],
  fallbackBudget: { maxRequests: 1000 },
  fallbackCircuitBreaker: { failureThreshold: 3, cooldownMs: 30_000 },
  fallbacks: [
    { provider: 'google', apiKey: process.env.GOOGLE_MAPS_API_KEY! },
    { provider: 'here', apiKey: process.env.HERE_API_KEY! },
  ],
});

See the Python and PHP equivalents.

Attempt history

Each attempt reports a provider and one of matched, no_results, low_confidence, error, or skipped. Errors include the SDK error; skipped attempts include budget_exhausted, circuit_open, or unsupported_country.

fallbackReason / fallback_reason describes the triggering primary condition even when no backup is configured or selected. provider identifies the returned result set. For example, primary can remain the selected provider with reason low_confidence after backups are exhausted.

Budget

fallbackBudget.maxRequests / FallbackBudget(max_requests=...) caps combined backup HTTP calls made by geocode, reverse geocode, and autocomplete for the lifetime of one client. Failed and empty responses count. Reservations happen before network calls, so calls sharing a client respect the cap under supported concurrency. Selection-resolution lookups are separate calls and do not consume this budget.

Zero disables backup provider selection for those three operations. Without a budget, those backup calls are unlimited. Exhausted providers are recorded as skipped. A configured provider can still resolve its own suggestion even when the budget is zero or exhausted. This is a request cap, not a currency budget.

Circuit breaker

The optional breaker tracks consecutive failures separately for each backup provider during geocode, reverse geocode, and autocomplete. At failureThreshold / failure_threshold, the provider is skipped for cooldownMs / cooldown_ms. Resolution neither checks nor updates circuit state.

After cooldown, one probe is allowed. A successful response, including empty results, closes the circuit; failure opens it again. Other providers remain available. Cancellation and caller deadline expiration do not count as provider failures. A reserved call still consumes budget, and opening a circuit does not cancel calls already in progress.

Reuse your client to share budget and breaker state. These controls are in memory and reset with a new client or process. PHP applications often create clients per incoming request, which also resets state. Provider account quotas are needed for limits shared across workers or servers.

Provider data

Fallback calls use your Google/HERE account and send addresses or coordinates directly to that provider. exclude_sources filters only primary results. Results from different providers are not merged or cached.

In C#, configure Fallbacks, FallbackOn, ConfidenceThreshold, MaxFallbackRequests, and FallbackCircuitBreaker on ClientOptions. See the .NET reference.