What are the gl and hl parameters?

The gl and hl parameters are Google search settings passed with a query. gl is a two-letter country code that tells Google which country to return results for, and hl is a language code that sets the interface language. Together they let you approximate what searchers in a given market see.

Last updated:

What does gl change?

gl, usually read as geolocation, sets the country the search is run for. It takes two-letter country codes such as us, ca, de, fr, in or br. Changing it changes which pages rank, because Google favors results relevant to that country: local retailers, local news outlets, country-specific domains and pages in the local language. A query like "tax filing deadline" gives different answers in the United States and Canada.

When you search on Google yourself, Google estimates your location from signals such as your IP address. In an API request, setting gl explicitly removes that guesswork, so the results do not depend on where your server happens to run.

What does hl change?

hl sets the language of Google's interface: buttons, labels and some generated text. It also influences results, since it signals which language the searcher understands. Language codes are usually two letters, such as en, es, de or ja. hl does not restrict results to that language; pages in other languages can still appear when they are relevant.

How do you combine gl and hl?

Match both to the market you care about. For Spanish speakers in Mexico, use gl mx with hl es; for English speakers in Canada, gl ca with hl en; for French speakers in Canada, gl ca with hl fr. Mixing them on purpose is also useful, for example gl us with hl es to see what Spanish-language searchers in the United States get.

Note what these parameters do not do. They set a country and a language, not a city. BestSERP accepts gl and hl on every endpoint but does not offer a city-level location parameter, so for local results put the city in the query, such as "dentist in Austin", and use the /places or /maps endpoints for business listings.

Keep the values fixed when you compare results over time. If gl or hl changes between runs, a change in rankings could come from the settings rather than from the search engine, and the history becomes hard to interpret.

Example

Same topic, three markets: each body sent to POST /search returns the results for that country and language.

{"q": "running shoes", "gl": "us", "hl": "en"}
{"q": "running shoes", "gl": "ca", "hl": "en"}
{"q": "tenis para correr", "gl": "mx", "hl": "es"}

Start with 3,000 free searches

No credit card. Sign in with Google, create a key, send your first request.