Страны и языки в Google: параметры gl и hl

Регион и язык выдачи Google задаются двумя параметрами: gl - страна, hl - язык интерфейса. Город к ним добавляется третьим - uule или числовым ID региона. Ниже - что делает каждый, кто побеждает при споре и полные списки значений: 252 стран и 155 языков.

Страна задаёт выдачу

gl - двухбуквенный код страны: ru, by, de, us. Это главный рычаг: он решает, из какой страны Google берёт выдачу. По запросу «новости» с gl=ru, gl=by и gl=kz получаются три выдачи без единого общего адреса: ria.ru и lenta.ru, belta.by и onliner.by, tengrinews.kz и ktk.kz.

Выбор домена на это не влияет: google.de и google.com.br давно отдают то же, что google.com, - подробнее в статье про домены Google по странам. Страну задаёт gl, а не адрес в строке браузера.

Что с чем сочетается

Когда параметры тянут в разные стороны, выигрывает не тот, что стоит раньше в запросе. Проверено так же, как для Bing: каждому параметру давалось своё значение, и по выдаче видно, чью сторону взял Google. Каждый случай прогонялся дважды, сравнивались наборы адресов целиком.

Вывод из первых трёх строк: страну задавайте через gl, а город - через uule или ID региона, и следите, чтобы они не спорили. Проще всего передавать только region: API сам соберёт из него и город, и gl той же страны. Как Google привязывает выдачу к городу, разобрано в статье про UULE.

Язык интерфейса - не только надписи

hl прежде всего переводит интерфейс: «Все», «Картинки», «Новости» становятся «All», «Images», «News» или «Alle», «Bilder». Но на выдачу он тоже влияет - слабее, чем страна, и не на всех запросах.

• На запросе, привязанном к месту, язык почти ничего не меняет: «hotel berlin» с gl=de даёт одну и ту же выдачу при hl=de и hl=en.
• На запросе, который можно понять на любом языке, Google подмешивает документы на языке интерфейса: «covid» с gl=fr и hl=en совпадает с французской выдачей (hl=fr) только на 0.54 - вместо части французских изданий приходят англоязычные.

Поэтому hl лучше ставить на языке, на котором ищут ваши пользователи, а не на том, на котором удобнее читать интерфейс.

Формы записи

Язык можно передать голым кодом (en) или локалью в том виде, в каком её пишет браузер (en-GB, en-US): вторая часть - страна из списка ниже. На выдачу страна в локали не влияет - hl=en-GB и hl=en при gl=gb дают одно и то же, страну по-прежнему решает gl.

Несколько вариантов - отдельные языки Google, а не язык со страной: pt-br и pt-pt, zh-cn, zh-tw и zh-hk, es-419. Голый pt Google понимает как бразильский португальский. Иврит у Google исторически iw, но he тоже принимается.

Незнакомый язык и язык по умолчанию

На незнакомый код Google не отвечает ошибкой: hl=zz молча превращается в английский. Со стороны это выглядит как работающий запрос. Наш API такой код не пропускает - отвечает ошибкой 422 до обращения к поисковику, так что опечатка не станет английской выдачей.

Если hl не передан, интерфейс будет русским при gl=ru (и когда страна тоже не указана) и английским для остальных стран.

Страны: 252 кодов

gl - код страны по ISO 3166-1 alpha-2 в нижнем регистре. Для Великобритании подходят оба кода: и стандартный gb, и привычный Google uk - выдача у них одна.

Языки интерфейса: 155

Список собран из меню языков в настройках Google и из таблицы языков интерфейса в его документации. Меню у Google зависит от того, откуда его открывают, поэтому в таблице языков больше, чем вы увидите в своих настройках. Редкие из них Google может не поддерживать в интерфейсе - тогда страница будет на английском, а выдача останется той же.

Что выбрать под задачу

• Выдача города - передавайте region: страна подставится сама. Найти ID можно в справочнике регионов Google.
• Выдача страны в целом - такой у Google нет: без города он возьмёт место из адреса запроса. Передавайте region или uule города, который считаете типичным, обычно столицы.
• Язык - hl на языке ваших пользователей. В многоязычной стране выбирайте под ту аудиторию, чью выдачу снимаете: gl=by&hl=ru или gl=by&hl=be.

Если не передать ничего о месте - ни страну, ни язык, ни регион, ни uule, ни координаты, - API подставит Москву с gl=ru и hl=ru. Подробности - в документации.

Примеры

curl "https://jsonseo.ru/api/google?q=новости&gl=by&hl=ru&key=ВАШ_КЛЮЧ"
curl "https://jsonseo.ru/api/google?q=hotel+berlin&gl=de&hl=de&key=ВАШ_КЛЮЧ"
curl "https://jsonseo.ru/api/google?q=weather&gl=in&hl=hi&key=ВАШ_КЛЮЧ"

Таблицы строятся из того же справочника, по которому API проверяет параметры gl и hl.