Localize Search Results by Language and Region

const API_KEY = 'YOUR_API_KEY';
const CX = 'YOUR_SEARCH_ENGINE_ID';
const BASE_URL = 'https://www.googleapis.com/customsearch/v1';

/**
 * Perform a localized search.
 *
 * @param {string} query          - The search query
 * @param {object} options
 * @param {string} options.lr     - Language restrict (e.g. 'lang_fr')
 * @param {string} options.gl     - Country bias (e.g. 'fr')
 * @param {string} options.cr     - Country restrict (e.g. 'countryFR') — optional
 * @param {string} options.hl     - Host language for UI strings (e.g. 'fr')
 * @param {number} options.num    - Results per page (1–10)
 * @param {string} options.safe   - SafeSearch setting
 */
async function localizedSearch(query, { lr, gl, hl, cr, num = 10, safe = 'active' } = {}) {
  const params = new URLSearchParams({ key: API_KEY, cx: CX, q: query, num, safe });

  if (lr) params.set('lr', lr);
  if (gl) params.set('gl', gl);
  if (hl) params.set('hl', hl);
  if (cr) params.set('cr', cr);

  const response = await fetch(`${BASE_URL}?${params}`);

  if (!response.ok) {
    const err = await response.json().catch(() => ({}));
    throw new Error(err?.error?.message ?? `HTTP ${response.status}`);
  }

  return response.json();
}

// French results biased toward France, with French UI strings
const frenchResults = await localizedSearch('apprentissage automatique', {
  lr: 'lang_fr',
  gl: 'fr',
  hl: 'fr',
});

// Japanese results biased toward Japan
const japaneseResults = await localizedSearch('機械学習', {
  lr: 'lang_ja',
  gl: 'jp',
  hl: 'ja',
});

// English results from the UK only (hard restrict)
const ukNews = await localizedSearch('budget announcement', {
  lr: 'lang_en',
  gl: 'gb',
  cr: 'countryGB',
  hl: 'en',
});

import requests

API_KEY = "YOUR_API_KEY"
CX = "YOUR_SEARCH_ENGINE_ID"
BASE_URL = "https://www.googleapis.com/customsearch/v1"


def localized_search(
    query: str,
    lr: str | None = None,
    gl: str | None = None,
    hl: str | None = None,
    cr: str | None = None,
    num: int = 10,
    safe: str = "active",
) -> dict:
    """
    Perform a localized Custom Search API request.

    Args:
        query: The search query string.
        lr:    Language restrict — e.g. 'lang_de' for German pages.
        gl:    Country bias — e.g. 'de' for Germany.
        hl:    Host language for API UI strings — e.g. 'de'.
        cr:    Country restrict — e.g. 'countryDE' (hard filter, use sparingly).
        num:   Results per page (1–10).
        safe:  SafeSearch — 'active' or 'off'.

    Returns:
        Parsed JSON response dict.
    """
    params: dict = {
        "key": API_KEY,
        "cx": CX,
        "q": query,
        "num": num,
        "safe": safe,
    }

    if lr:
        params["lr"] = lr
    if gl:
        params["gl"] = gl
    if hl:
        params["hl"] = hl
    if cr:
        params["cr"] = cr

    response = requests.get(BASE_URL, params=params, timeout=10)
    response.raise_for_status()
    return response.json()


# German results biased toward Germany, with German UI strings
german_results = localized_search(
    "maschinelles Lernen",
    lr="lang_de",
    gl="de",
    hl="de",
)

# Brazilian Portuguese results
br_results = localized_search(
    "aprendizado de máquina",
    lr="lang_pt",
    gl="br",
    hl="pt",
)

# Japanese results
ja_results = localized_search(
    "機械学習",
    lr="lang_ja",
    gl="jp",
    hl="ja",
)

# French results, biased toward France
curl -G "https://www.googleapis.com/customsearch/v1" \
  --data-urlencode "key=YOUR_API_KEY" \
  --data-urlencode "cx=YOUR_SEARCH_ENGINE_ID" \
  --data-urlencode "q=apprentissage automatique" \
  --data-urlencode "lr=lang_fr" \
  --data-urlencode "gl=fr" \
  --data-urlencode "hl=fr" \
  --data-urlencode "safe=active"

# UK English results only (hard country restrict)
curl -G "https://www.googleapis.com/customsearch/v1" \
  --data-urlencode "key=YOUR_API_KEY" \
  --data-urlencode "cx=YOUR_SEARCH_ENGINE_ID" \
  --data-urlencode "q=budget announcement" \
  --data-urlencode "lr=lang_en" \
  --data-urlencode "gl=gb" \
  --data-urlencode "cr=countryGB" \
  --data-urlencode "hl=en"