Coverage and limits
Engines
The API serves ChatGPT, Gemini, Perplexity, Copilot, Grok, Google AI Mode, Google Search, and Google News.
Countries
country takes an ISO 3166-1 alpha-2 code. GET /v1/countries?model=<engine> returns the list an
engine serves. A country absent from an engine's list is refused with a 400.
| Engine | Countries |
|---|---|
| ChatGPT | 213 countries |
| Gemini | 213 countries, plus US states |
| Perplexity | Any country |
| Copilot | Any country |
| Grok | Any country |
| Google AI Mode | 213 countries, down to the city |
| Google Search | 213 countries, down to the city |
| Google News | 71 countries |
Google News serves the 71 countries with a Google News edition: Argentina, Australia, Austria, Bangladesh, Belgium, Botswana, Brazil, Bulgaria, Canada, Chile, China, Colombia, Cuba, Czechia, Egypt, Estonia, Ethiopia, Finland, France, Germany, Ghana, Greece, Hong Kong SAR China, Hungary, India, Indonesia, Ireland, Israel, Italy, Japan, Kenya, Latvia, Lebanon, Lithuania, Malaysia, Mexico, Namibia, Netherlands, New Zealand, Nigeria, Norway, Pakistan, Peru, Philippines, Poland, Portugal, Romania, Russia, Saudi Arabia, Senegal, Serbia, Singapore, Slovakia, Slovenia, South Africa, South Korea, Spain, Sweden, Switzerland, Taiwan, Tanzania, Thailand, Türkiye, Uganda, Ukraine, United Arab Emirates, United Kingdom, United States, Venezuela, Vietnam, and Zimbabwe.
US states
state narrows a request to one US state and is only valid with country: "US"
on Gemini.
GET /v1/states?country=US lists the codes, the District of Columbia (DC) included.
State targeting is best-effort: it steers the market the answer is taken from, not a coordinate, and engines localize by signals beyond the address.
Targeting fields per engine
| Field | Values | Engines | Notes |
|---|---|---|---|
country | ISO 3166-1 alpha-2 | Every engine | Optional on Google Search, Google News and Google AI Mode; required on the rest. |
state | Two-letter code, e.g. CA | Gemini | Only valid with country "US". |
gl | ISO 3166-1 alpha-2, e.g. us | Google Search, Google News, Google AI Mode | Google's name for country, an alias of the same geography; sending both with different values is a 400. |
location | Free-form place, e.g. Austin,Texas,United States | Google Search, Google AI Mode | City-level targeting. |
uule | Location-name UULE (w+CAIQICI…) | Google Search, Google AI Mode | A pre-built UULE instead of a location name; mutually exclusive with location. The coordinate form (a+…) is refused with a 400. |
hl | Interface language, e.g. fr | Google Search, Google News, Google AI Mode | The UI language the answer is taken in. Without it, the country's own language. |
Google News takes country (or gl) and hl only, not state or location.
Google Search and Google AI Mode take a city by location or uule, the interface language by hl,
and device. Without location or uule, they are localized to the requested country.
When a request cannot be placed
A request for a country absent from the engine's list, or with a field the engine does not take, is refused with a
400. A request that cannot be placed once accepted fails with 502 EXTERNAL_SERVICE_ERROR. Neither is charged.
Retries of a 400 do not help: pick a listed country or drop the field.