Skip to main content
GET
Google AI Mode search

Country and language

gl and hl are passed to Google as its country (market) and language parameters. They shape the answer Google writes. They do not choose where the request exits from: AI Mode is answered from a pool of pre-warmed Google sessions whose exits are in a fixed set of countries, so do not expect the exit IP to be in the gl country. To answer as if the user were in a particular city or district, use location targeting.

Location targeting

AI Mode answers “near me” and other local questions for the place you give it, down to the city or district, whatever country the request exits from. Pass one of these: When you send location without gl, gl becomes the location’s country: location=Wonju-si answers with gl=kr. A gl you send is always kept. lat/lon and uule leave gl at its default of us, so set gl yourself when the place is outside the US. hl is never inferred; set it for an answer in the local language.
Google decides whether an answer uses the location. Most located answers are localized to the city or district. Some still answer for the country’s default city, or ask where you are. Those answers are billed like any other. To check, look for the place in markdown.
Answers verified on 2026-11-10:

Location in the response

A located answer adds a location object, and country is the effective gl. Responses to requests without location, uule, lat or lon are unchanged.

Location errors

These requests are rejected with 422 and a {"detail": "..."} body: A lat or lon outside its range fails standard parameter validation, also with 422. A located request that cannot be answered right now returns 503. Located requests have no fallback to a browser render, so they can return 503 where the same question without a location would have been answered. They are not billed; retry as described below.

Temporary unavailability

If the service cannot obtain a complete AI Mode answer, it returns 503 Service Unavailable instead of an empty answer or a misleading 404. It does not substitute a regular search result or an AI Overview for an AI Mode answer. Wait at least the time specified by the response’s Retry-After header before retrying. Do not assume a fixed delay: a recently failed identical prompt can require a 300-second wait. Use bounded retries with backoff and reduce concurrency if failures continue. A retry is not guaranteed to succeed. Failed requests do not consume credits. See credits and pricing.

Authorizations

x-api-key
string
header
required

Query Parameters

q
string
required

Search query for AI-generated response

gl
string
default:us

Google country (market) code. It shapes the answer; it does not pick the exit IP's country. Defaults to the location's country when location is set.

hl
string
default:en

Language code

include_html
boolean
default:true

Include the raw answer_html (full answer body HTML) in the response for maximum parity. It can be 100s of KB — set false when you only need the structured text_blocks + markdown.

location
string | null

Answer as if the user were here: a Google canonical location name (e.g. Wonju-si,Gangwon-do,South Korea), a Google criteria ID, or an unambiguous short name within gl. Use only one of location, uule, or lat/lon.

uule
string | null

A Google UULE value in its w+ (canonical name) or j+ (coordinates) form.

lat
number | null

Latitude of the user's location (with lon).

Required range: -90 <= x <= 90
lon
number | null

Longitude of the user's location (with lat).

Required range: -180 <= x <= 180

Response

Successful Response

Response for GET /api/v1/ai-mode/search.

query
string
required
text_blocks
AiTextBlock · object[]
references
AiReference · object[]
language
string
default:en
country
string
default:us

The effective gl: the location's country when location set it and gl was not sent.

markdown
string | null

Compact Markdown rendering of the whole answer.

answer_html
string | null

Raw answer body HTML (script/style stripped). Omitted when include_html=false.

location
AiModeLocation · object | null

Present only on located requests (location, uule or lat/lon).