Как использовать API поисковых подсказок Google / Хабр

Google Autocomplete (Google Suggest) — механизм автодополнения поисковых запросов, который отображает подсказки в реальном времени. Несмотря на отсутствие официальной документации, его поведение достаточно стабильно и широко используется в SEO, анализе поискового интента и сборе семантики.

В этой статье разобраны параметры запроса, форматы ответа и практические примеры работы с endpoint:

Базовый запрос к API

https://suggestqueries.google.com/complete/search

Метод: GET
Все параметры передаются через query string. Для тестирования можно скопировать запрос и вставить в окно браузера и нажать ENTER

https://suggestqueries.google.com/complete/search?client=chrome&q=seo

У вас должен скачаться файл txt с JSON ответом. Его можно вставить в любой онлайн сервис JSON Viewer и увидеть запросы:

Обязательные параметры API

Параметр	Описание
q	Строка поискового запроса
client	Тип клиента (влияет на формат ответа)

Параметр client и формат ответа

client	Формат ответа
chrome	JSON
firefox	JSON
toolbar	XML

На практике чаще всего используется client=chrome. Но в то же время при использовании client=firefox подсказки немного (до 30% ) могут отличаться. Поэтому для максимального результата комбинируйте запросы.

Пример JSON-ответа

[
  "seo",
  [
    "seo это",
    "seo оптимизация",
    "seo специалист"
  ],
  [],
  {
    "google:suggesttype": ["QUERY", "QUERY", "QUERY"],
    "google:suggestrelevance": [1250, 620, 580],
    "google:verbatimrelevance": 1300
  }
]

Структура ответа

Исходный запрос
Массив подсказок
Зарезервированное поле (часто пустое)
Метаданные подсказок

Suggesttype в 99% запросов бывает QUERY, но есть и другие варианты:

NAVIGATION: Прямая ссылка на сайт (URL). Вместо того чтобы предлагать поисковый запрос, API предлагает сразу перейти на конкретный ресурс (например, при вводе «facebook» первой подсказкой может быть прямой адрес сайта).
ENTITY: Подсказка, связанная с конкретной сущностью из Google Knowledge Graph (люди, места, организации). Часто сопровождается дополнительными метаданными, такими как краткое описание или изображение.
CALCULATOR: Математический ответ. Если запрос похож на вычисление (например, «5+5»), API может вернуть готовый результат.
PERSONALIZED: Подсказка, основанная на личной истории поиска пользователя или его активности.
TAIL: Так называемые «хвостовые» подсказки, которые дополняют текущий ввод пользователя, предлагая логическое завершение фразы.

А вот suggestrelevance - это релевантность с точки зрения Google. Параметр абстрактный, чем больше значение - тем более релевантный запрос. Для витальных, брендовых запросов, если результат около 1250-1300 - это почти релевантный ключ. Но сильно на него не надейтесь, так Google часто ошибается, особенно для омонимов.

Verbatimrelevance еще интереснее.
Например если вы написали "seo" и verbatimrelevance равен 1300, а подсказка "seo это" имеет 1250, то нажатие Enter просто отправит вас на страницу выдачи по запросу "seo". Если бы было наоборот (подсказка 1300, а ввод 1250), браузер мог бы агрессивнее предлагать авто дополнение прямо в адресной строке.
На практике я сталкивался и другими значениями, а не 1300 и 1250, поэтому жестко не привязывайтесь к этим параметрам.

География и язык

Все запросы геозависимые, поэтому если не указывать страну то запрос будет учитывать ваш IP. Если вам нужны данные по конкретному языку или стране, можно передавать параметры в get запросе.

Параметр	Назначение	Пример
hl	Язык интерфейса	en, de, fr
gl	Страна (ISO-2)	US, DE, UA

?client=chrome&q=seo&hl=en&gl=US

На практике не сильно надейтесь на указание страны и языка, так как Google подмешивает иногда ключи из других стран или языков. Это связано с использованием VPN.

Источник подсказок (ds)

Получать подсказки можно не только в поиске Гугла, но и в Youtube, Товарах и Google News.

ds	Источник
(пусто)	Обычный поиск
yt	YouTube
sh	Товары / Shopping
n	Новости

?client=chrome&q=seo&ds=yt

Расширение подсказок (ключевая техника)

Для получения большего количества подсказок используется приём:

<ключ> + " " + символ

Примеры:


seo a
seo b
seo c
seo 0
seo 1

Этот подход позволяет эффективно собирать long-tail запросы и выявлять поисковый интент. На практике для высокочастотных запросов такой метод позволяет получить в 5-9 раз больше ключей. Этот метод можно применить и для каждого полученного ключа.

Пример кода (Python)

import requests
def google_suggest(query, hl="en", gl="US", ds=None):
url = "https://suggestqueries.google.com/complete/search"
params = {
"client": "chrome",
"q": query,
"hl": hl,
"gl": gl
}
if ds:
params["ds"] = ds
response = requests.get(url, params=params, timeout=5)
response.raise_for_status()
return response.json()

data = google_suggest("seo")
print(data[1])

Массовый сбор подсказок (a–z, 0–9)

import string
import time
def expand_keywords(base):
results = {}
for ch in string.ascii_lowercase + string.digits:
q = f"{base} {ch}"
try:
data = google_suggest(q)
results[q] = data[1]
except Exception:
pass
time.sleep(3.2)
return results
keywords = expand_keywords("seo")

На практике осторожнее с таким методом, так как от Гугла можно получить бан по IP.

Пример кода (JavaScript)

async function googleSuggest(query, hl = 'en', gl = 'US', ds = null) {
  const params = new URLSearchParams({
    client: 'chrome',
    q: query,
    hl,
    gl
  });
if (ds) params.set('ds', ds);
const url = 'https://suggestqueries.google.com/complete/search?' + params;
const response = await fetch(url);
const text = await response.text();
return JSON.parse(text);
}
googleSuggest('seo').then(data => {
console.log(data[1]);
});

JSONP (callback)

Для обхода CORS можно использовать параметр callback:

?callback=myFunction

Ответ будет обёрнут в вызов функции, который необходимо очистить перед разбором JSON.
Вообще если у вас любые запросы к API подсказкам не работают в браузере, то скорее проблема именно в CORS. Проверить в Хроме это можно нажав в окне правую клавишу мыши и выбрав "Просмотреть код", в консоли будут красные ошибки от CORS.

Ограничения и практические рекомендации

API неофициальный, это хак, может быть отключен в любой момент
Возможны блокировки при высокой частоте запросов - используйте задержки в своих скриптах.
Не завязывайтесь на жёсткую структуру ответа, так как иногда ловил очень удивительные результаты

Основные области применения

SEO-инструменты
Анализ поисковых интентов
Сбор long-tail семантики
YouTube SEO
Анализ спроса

Я на практике использую для поиска скрытого интента и расширения запросов для сущностей. Главная проблема поисковых подсказок Гугла - это проблема с омонимами, при массовом парсинге они попадают в семантическое ядро. Тем не менее эта проблема легко решается кластеризацией или более дешевым методом - проверкой коcинусной близости с помощью BERT.

Как использовать API поисковых подсказок Google