Country routing
Choose the primary API or a backup using a country hint.
For forward and reverse geocoding, the SDKs use the primary API first for Canada (CA), the United States (US), and Mexico (MX). Geographic coverage depends on the deployed dataset. For geocode and reverse, an SDK routing hint is not sent to the primary API and does not restrict results; for search, the SDK also sends the normalized country as a filter.
Country hints
SDK geocode, search, and reverse requests accept an optional country string. Recognized ISO alpha-2 codes, alpha-3 codes, and English country names normalize to uppercase alpha-2. Examples include US, USA, and United States.
| Hint | Routing |
|---|---|
| Missing, empty, or whitespace | Primary first |
Normalizes to CA, US, or MX | Primary first |
| Any other nonempty string | Skip primary; try configured backups in order |
The country hint is not sent to primary geocode or reverse requests. For a forward backup query, the SDK includes the normalized code, or the original trimmed string when unrecognized. Check spelling: a nonempty unknown country also bypasses primary.
For reverse requests, supply the hint only when you already know the country. Without it, even coordinates outside North America go to primary first.
International requests
Configure Google, HERE, or both for requests outside the primary SDK countries. A request with country: "GB", for example, records the primary attempt as skipped with unsupported_country, then tries backups. The response fallback reason is also unsupported_country.
Country routing is independent of fallbackOn / fallback_on: an empty trigger list does not disable international routing. Backup budgets and circuit breakers still apply.
If no configured backup returns results for an unsupported country, the SDK raises GeocodingError with code unsupported_country and the full attempt history. See fallback configuration.
Autocomplete country restrictions
For autocomplete, country is required and must normalize to a recognized country. Primary autocomplete restricts suggestions to CA, US, or MX and sends the normalized country as a query parameter. Other recognized countries route to configured backups, independently of the trigger list but subject to fallback budgets and circuit breakers. Unknown or blank countries fail SDK validation before networking. Over HTTP, country is optional and accepts any 2- or 3-letter code.
Selection resolution uses the suggestion's provider and ID; it does not take a country hint or run country routing.
Returned country values
The API returns ISO alpha-2 codes such as US. SDK results normalize recognized values to US, CA, GB, and other alpha-2 codes; unknown or missing values become "".
The embedded table covers 249 assigned ISO countries and territories. Python and PHP use the frozen names and aliases from the TypeScript SDK's table. The selected backup's raw response remains unchanged in providerResponse / provider_response.