Google gl and hl Parameters Explained, with Real Examples
Michael Carter · · 12 min read

Key takeaways
- gl sets the searcher's country with a two-letter code such as us, gb or de; hl sets Google's interface language, such as en, fr or pt-BR. Neither targets a city.
- In our November 18, 2026 test, "income tax calculator" in the US, the UK and Canada (all in English) returned top-10 pages with no site in common, each with its own country's tax authority among the results.
- Switching hl to Spanish in the US kept 6 of 9 sites and every title in English, the same overlap as fetching the English page twice: for an English query, hl changes little.
- hl matters most for queries with no language of their own: "iphone 17" in Canada returned 5 French-language pages of 7 with hl=fr and none of 8 with hl=en.
- Check where each search ran: BestSERP's ipCountry field names the country of the IP, which can differ from gl when no IP there is free.
The gl and hl parameters set the country and the language of a Google search. gl is a two-letter country code (us, gb, de) that decides which country's results you get. hl sets the interface language (en, fr, pt-BR) and only nudges which pages rank. Neither one targets a city.
This guide is for developers and SEOs who pull localized Google results through a SERP API (new to them? Start with what a SERP API is and how it works). It explains each parameter from Google's documentation, then shows what changed in real results when we varied them on November 18, 2026, followed by valid codes, common mistakes and tested Python code.
What the gl and hl parameters do
The gl parameter tells Google which country the searcher is in; hl sets the language of Google's interface. Google documents both for its Custom Search JSON API, and SERP APIs such as BestSERP use the same names:
- gl is the "Geolocation of end user", a two-letter country code. Google says it "boosts search results whose country of origin matches the parameter value" (cse.list reference, last updated August 21, 2024, read November 18, 2026).
- hl "Sets the user interface language". Its value "may affect search results, especially on international queries" when no language filter is set, and "may promote search results in the same language as the user's input language" (JSON API reference).
Google's Search Help says the same for google.com: the interface language "helps Google know what language to show you for search results. However, it doesn't only show results in that language." The language you type in, your device's languages and your location count too (How Google knows what language to show).
In BestSERP, a Google SERP API, gl defaults to us and hl to en. The gl value also decides where the search runs from: an IP address in that country when one is free, otherwise another country, and every response names it in the ipCountry field (search endpoint reference). The glossary entry on gl and hl has the short definition; this guide shows the effect on real pages.
gl vs hl: country vs language
gl picks the market; hl picks the interface language and gives the ranking a hint. Side by side:
| gl | hl | |
|---|---|---|
| Sets | The searcher's country | The interface language |
| Values | Two-letter country code: us, gb, ca, de | Language code, sometimes with a region: en, fr, pt-BR |
| Effect in our test | Replaced every site: US, UK and Canada shared none | English query: Spanish kept 6 of 9 US sites, all titles stayed English |
| In Google's settings | Region setting | Display language |
| Does not | Target a city | Filter results to one language |
| BestSERP default | us | en |
Example: one query, five combinations (real results)
We searched "income tax calculator" five ways with BestSERP's /search endpoint: three countries in English, plus a Spanish interface in the US and a French interface in Canada. Each country has its own tax system, so a local page is easy to spot. All searches ran from the country we asked for (ipCountry equal to gl). We fetched each page twice; when the fetches disagreed, a third decided which list to use.

Same language, three countries: gl replaces the results
Changing only gl replaced the whole page: the US, UK and Canadian pages shared no site at all. Each country's government showed up: apps.irs.gov at 6 in the US, gov.uk at 1 and 9 and mygov.scot at 5 in the UK, canada.ca at 3 in Canada.
Local domains followed the country. 4 of 9 UK results were on .uk domains and 5 of 9 Canadian results on .ca, against none on .us in the US. One brand split by market: TurboTax ranked with turbotax.intuit.com in the US and turbotax.intuit.ca in Canada.
Same country, another language: hl barely moved an English query
Changing hl moved far less. In the US, the Spanish interface (hl=es) kept 6 of the 9 sites on the English page, exactly as many as a second fetch of the English page kept, and all 9 titles stayed English. hl neither translates the query nor filters the results.
In Canada, the French interface returned no site from the English page, yet all 9 titles were still English (small calculator sites such as truenorthbenefits.ca, plus a Google Play app). hl does not get all the credit: one of our three English fetches returned a similar list, with 4 of its 9 sites on the French page. Measure hl against a fresh fetch of the same settings.

Where hl matters: a query with no language of its own
hl matters most when the query does not say which language you want. We searched "iphone 17" in Canada once with each interface language:
| hl=en | hl=fr | |
|---|---|---|
| Organic results | 8 | 7 |
| French-language pages | 0 | 5 |
| Examples | walmart.ca/en, bestbuy.ca/en-ca | apple.com/ca/fr, fizz.ca/fr, bell.ca, fr.wikipedia.org |
The two pages had no site in common: Google's "may promote search results in the same language" at work. With one fetch each, read this as an example, not a measurement.
A non-English query: France vs Canada
A French query already tells Google the language; gl still picks the market. We searched "calcul impôt sur le revenu" with hl=fr:
- France (gl=fr): all 9 titles in French, 7 of 9 results on .fr domains, 6 of them government pages (impots.gouv.fr, economie.gouv.fr, service-public.gouv.fr).
- Canada (gl=ca): none of three fetches shared a site with France's page. The first two agreed and held mostly English-language calculators (3 and 2 French titles of 9). The third, less than two minutes later, returned a different list with 9 French titles, including canada.ca's French pages.
France's official simulator never appeared in Canada, but the Canadian page was not stable that morning: fetch twice before you report.
Valid gl and hl values
gl takes a lowercase two-letter country code and hl a language code. Google's Custom Search reference lists 239 gl values and 83 interface languages (page last updated August 21, 2024); these are the common ones:

Three details trip people up:
- United Kingdom: gb or uk. The ISO 3166 code is GB (as listed in the UN Statistics Division's M49 table), but Google's gl table lists uk. BestSERP accepted both in our test: gl=uk ran from the UK (
ipCountry: uk) and returned the same 8 sites as gl=gb. - Country and language codes differ. Japan is gl=jp with hl=ja, South Korea kr with ko, Viet Nam vn with vi, Brazil br with pt-BR. Google uses iw for Hebrew.
- Filters are separate parameters. Google's Custom Search API filters by language with lr and by country of origin with cr. BestSERP has neither and refuses unknown parameters, so to get pages in a language, write the query in it.
We tested only en, es and fr through BestSERP; regional codes such as pt-BR are from Google's list.
Common mistakes with the gl and hl parameters
Most surprises come from expecting one parameter to do another's job:
| Mistake | What happens | Do this instead |
|---|---|---|
| Picking the country with a country domain (google.co.uk) | Since 2017 Google picks the country from your location, not the domain; since April 2025 country domains redirect to google.com (Google, April 15, 2025) | Set gl. Google's Custom Search API deprecated its domain parameter: "Use the gl parameter for a similar effect" |
| Expecting hl to switch the results' language | Our English query kept 9 of 9 English titles with hl=es and hl=fr; Google says the display language "doesn't change the language of your search results" (Search Help) | Write the query in the target language and set hl to match |
Sending a city in location |
BestSERP answers 400 unsupported_parameter: "location is not supported yet; use gl (country) and hl (language)" (not charged) |
Put the city in the query: "accountant in Toronto" |
| Trusting gl without checking where the search ran | A page fetched from another country is not that country's page | Compare ipCountry with gl; re-fetch or drop mismatches |
| Comparing single fetches | 4 of our 7 settings came back as a different list on the first re-fetch | Fetch twice; when the lists differ, use the one that repeats |
Reading _gl in a URL as the country |
_gl is Google Analytics' parameter for carrying cookies between domains (Analytics Help); 8 of 9 results for "google gl parameter" were about it or Analytics |
Ignore it: the country is gl, without the underscore |
Using gl and hl parameters in a SERP API request
In a SERP API request, gl and hl are two fields next to the query. A BestSERP /search body for France in French:
{"q": "calcul impôt sur le revenu", "gl": "fr", "hl": "fr", "num": 10, "noCache": true}
The real answer after polling for final links, trimmed (November 18, 2026, 04:32 UTC):
{
"searchParameters": {"q": "calcul impôt sur le revenu", "gl": "fr", "hl": "fr", "num": 10, "page": 1,
"type": "search", "noCache": true, "engine": "google"},
"organic": [
{"position": 1, "title": "Simulateurs", "link": "https://www.impots.gouv.fr/simulateurs",
"source": "impots.gouv.fr", "domain": "impots.gouv.fr"}
],
"credits": 1,
"cached": false,
"linksPending": false,
"unresolvedLinks": 0,
"durationMs": 4622,
"ipCountry": "fr"
}
ipCountry names the country the search ran from, here the same as gl. Our script (tested November 18, 2026, Python 3.12.10, requests 2.34.2) runs a list of query, gl and hl combinations as fresh pages, waits for final links and prints where each search ran from:
import json
import os
import sys
import time
from concurrent.futures import ThreadPoolExecutor
from datetime import datetime, timezone
from pathlib import Path
import requests
API = "https://api.bestserp.com"
HEADERS = {"X-API-KEY": os.environ["BESTSERP_API_KEY"]}
OUT = Path(__file__).resolve().parents[1] / "data" / "raw"
JOBS = [ # (query, gl = country, hl = interface language)
("income tax calculator", "us", "en"),
("income tax calculator", "gb", "en"),
("income tax calculator", "ca", "en"),
("income tax calculator", "ca", "fr"),
("income tax calculator", "us", "es"),
("calcul impôt sur le revenu", "fr", "fr"),
("calcul impôt sur le revenu", "ca", "fr"),
]
def search(q: str, gl: str, hl: str) -> dict:
"""A fresh page (noCache) with final links. 429/502/503: wait and retry (failed searches are refunded)."""
body = {"q": q, "gl": gl, "hl": hl, "num": 10, "noCache": True}
for _ in range(5):
resp = requests.post(f"{API}/search", headers=HEADERS, json=body, timeout=130)
# 202 = still searching; linksPending = final URLs still arriving. Both: poll the request (free).
while resp.status_code == 202 or (resp.status_code == 200 and resp.json().get("linksPending")):
time.sleep(5)
resp = requests.get(f"{API}/requests/{resp.json()['requestId']}", headers=HEADERS, timeout=30)
if resp.status_code in (429, 502, 503):
time.sleep(int(resp.headers.get("Retry-After", 10)))
continue
resp.raise_for_status()
return resp.json()
raise RuntimeError(f"{q!r} {gl}/{hl}: still failing after 5 tries")
The second half saves each raw response and flags any page that ran from another country:
def run(job: tuple[str, str, str], rnd: str) -> None:
q, gl, hl = job
data = search(q, gl, hl)
data["fetchedAt"] = datetime.now(timezone.utc).isoformat(timespec="seconds")
OUT.mkdir(parents=True, exist_ok=True)
name = f"{gl}-{hl}-{q.replace(' ', '-')}-{rnd}.json"
(OUT / name).write_text(json.dumps(data, ensure_ascii=False, indent=1), encoding="utf-8")
ip = data.get("ipCountry", "?") # where the search ran from: compare it with gl before using the page
note = "" if ip == gl else " <- ran from another country, do not use"
top = ", ".join(item.get("domain") or item.get("source", "?") for item in data.get("organic", [])[:3])
print(f"gl={gl} hl={hl} {q!r}: from {ip}{note} | top 3: {top}")
if __name__ == "__main__":
with ThreadPoolExecutor(max_workers=4) as pool: # 4 at a time, far below 60 searches a minute
list(pool.map(run, JOBS, [sys.argv[1]] * len(JOBS)))
Output of the first round (python code/compare_gl_hl.py 1, 04:29:48 to 04:30:47 UTC, 7 credits):
gl=us hl=en 'income tax calculator': from us | top 3: smartasset.com, turbotax.intuit.com, calculator.net
gl=gb hl=en 'income tax calculator': from gb | top 3: gov.uk, moneysavingexpert.com, thesalarycalculator.co.uk
gl=ca hl=en 'income tax calculator': from ca | top 3: calculatetax.ca, mapletaxcalc.com, microhubb.com
gl=ca hl=fr 'income tax calculator': from ca | top 3: nuages.ca, bonnyville.ca.expertini.com, play.google.com
gl=fr hl=fr 'calcul impôt sur le revenu': from fr | top 3: simulateur-ir-ifi.impots.gouv.fr, boursorama.com, francetransactions.com
gl=us hl=es 'income tax calculator': from us | top 3: smartasset.com, calculator.net, turbotax.intuit.com
gl=ca hl=fr 'calcul impôt sur le revenu': from ca | top 3: moneymapcanada.com, financesimplifier.replit.app, maplecalc.ca
Three of these pages (both Canadian ones for the English query, and France) came back as a different list on the next fetch, so the examples above use the lists that repeated. The quickstart shows the request in other languages. Without code, the free SERP Checker takes a country and a language; for a full method, see how to check Google rankings in another country.
How we tested
- When: November 18, 2026, 04:29 to 04:36 UTC.
- Requests: 22 BestSERP
/searchcalls,num: 10, desktop,noCache: true, links polled until final (unresolvedLinks: 0everywhere); answers in 4.4 to 9.3 seconds; 22 credits, about one cent. The refusedlocationtest cost nothing. - Countries: every search ran from the country in gl (
ipCountryequal to gl, "uk" for gl=uk). - Repeats: the seven settings in the script were fetched twice, about 75 seconds apart. When the second fetch kept fewer than half of the sites, a third fetch one to two minutes later decided. "iphone 17" and gl=uk were fetched once.
- Counting: sites are the
domainfield. Title language comes from a word-list script checked by hand; a French-language page has a French title, a /fr/ path or a fr. host name.
Next steps
The gl and hl parameters answer different questions: gl says whose market you see, hl how the page speaks to you. To go further:
- How the request becomes JSON, and what it costs: our guide to SERP APIs.
- Rankings by market: checking Google rankings in another country, or our eight-country study of Google results.
- Every parameter of the endpoint: the /search reference.