Google Search API country and language targeting

Treat country and language as separate choices

The gl field controls the country used to localize results. The hl field controls the search interface and result language. They are independent, so a request can use English for a search targeted to Germany or German for the same country.

gsearch.dev accepts 239 country codes and these 5 language codes: en, bg, de, fr, es. Omit a field only when its documented default is right for the request.

Send explicit market combinations

Keep targeting values beside the query so every result can be traced to the market and language that produced it. The response repeats the normalized values in searchParameters.

const targets = [
  { q: "weather API", gl: "us", hl: "en", page: 1 },
  { q: "weather API", gl: "de", hl: "de", page: 1 },
  { q: "weather API", gl: "bg", hl: "bg", page: 1 }
];

for (const input of targets) {
  const response = await fetch("https://gsearch.dev/api/v1/search", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": process.env.GSEARCH_API_KEY
    },
    body: JSON.stringify(input),
    signal: AbortSignal.timeout(10_000)
  });

  if (!response.ok) throw new Error("Search failed with HTTP " + response.status);
  const result = await response.json();
  console.log(result.searchParameters, result.organic);
}

Compare localized results with fixed inputs

When comparing markets, keep q, page, and request timing as consistent as the use case allows. Change one targeting value at a time when you need to understand its effect.

Search results can change between requests. Store the query, gl, hl, page, request time, and returned URLs instead of treating one result set as permanent.

• Use ISO-style lowercase country codes accepted by the API.
• Use only a documented language code.
• Keep page between 1 and 10.
• Read normalized searchParameters before comparing results.

Validate codes before the request

An unsupported country, language, or page returns HTTP 400 and does not use a search credit. Validate user-selected values in your application before sending the request.

Use the API documentation for the readable list and the OpenAPI specification for the complete machine-readable enums.