Keywords API в формате DataForSEO: объём, подсказки и регионы

Данные Яндекс Wordstat в формате ответов DataForSEO: конверт tasks[] с status_code, status_message и result. Подходит, если ваш код уже разбирает этот формат. Для нативного формата Wordstat с названиями регионов есть Wordstat API.

Эндпоинт	Что делает
`POST /v1/keywords/search_volume`	Средний месячный объём и помесячная история для списка ключей
`POST /v1/keywords/suggestions`	Связанные ключевые слова с объёмом поиска
`POST /v1/keywords/locations`	Распределение спроса по регионам

Все запросы — с ключом в заголовке Authorization: Bearer <ключ> (см. Аутентификация). Полная схема — в справочнике proxy.seyka.ru/api-docs.

Коды регионов

location_code — код DataForSEO. Поддерживаются:

`location_code`	Регион
`2643`	Россия (по умолчанию)
`1012`	Москва
`1013`	Санкт-Петербург
`1014`	Екатеринбург
`1015`	Новосибирск
`1016`	Казань
`1017`	Нижний Новгород

Неизвестный код считается Россией, но в ответе location_code остаётся таким, как его передали.

Объём поиска

POST /v1/keywords/search_volume берёт помесячную динамику Wordstat за последний год и возвращает средний месячный объём для каждого ключа.

Поле	По умолчанию	Описание
`keywords`	—	Ключевые слова, обязательное, от 1 до 100
`location_code`	`2643`	Регион, см. коды регионов
`language_code`	`ru`	Возвращается в ответе как есть

curl -X POST "https://proxy.seyka.ru/v1/keywords/search_volume" \
  -H "Authorization: Bearer $SEYKA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keywords": ["купить телефон", "смартфон цена"], "location_code": 1012}'

{
  "tasks": [
    {
      "status_code": 20000,
      "status_message": "Ok.",
      "result": [
        {
          "keyword": "купить телефон",
          "location_code": 1012,
          "language_code": "ru",
          "search_volume": 45230,
          "competition": 0.7,
          "competition_level": "HIGH",
          "cpc": 0.45,
          "monthly_searches": [
            { "year": 2025, "month": 10, "search_volume": 44100 },
            { "year": 2025, "month": 11, "search_volume": 46900 }
          ]
        }
      ]
    }
  ]
}

Список до 100 ключей — один вызов. Каждый ключ — отдельный запрос к Wordstat, поэтому длинный список отвечает дольше. Если Wordstat не ответил хотя бы по одному ключу, весь запрос завершается ошибкой.

Подсказки

POST /v1/keywords/suggestions подбирает ключевые слова, связанные с исходным: языковая модель предлагает кандидатов, Wordstat проверяет их частотность, а выдача Яндекса по исходному ключу даёт оценку конкуренции. Результаты отсортированы по объёму поиска.

Поле	По умолчанию	Описание
`keyword`	—	Исходное ключевое слово, обязательное
`limit`	`50`	Сколько подсказок вернуть, не больше 100
`location_code`	`2643`	Регион, см. коды регионов
`language_code`	—	Принимается для совместимости; подсказки подбираются на русском

curl -X POST "https://proxy.seyka.ru/v1/keywords/suggestions" \
  -H "Authorization: Bearer $SEYKA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keyword": "натяжные потолки", "limit": 20, "location_code": 1012}'

{
  "tasks": [
    {
      "status_code": 20000,
      "status_message": "Ok.",
      "result": [
        {
          "seed_keyword": "натяжные потолки",
          "items": [
            { "keyword": "натяжные потолки цена", "search_volume": 18400, "competition": 0.62, "cpc": 0.45 },
            { "keyword": "натяжные потолки под ключ", "search_volume": 6100, "competition": 0.62, "cpc": 0.3 }
          ]
        }
      ]
    }
  ]
}

competition — одна оценка конкуренции по выдаче для всей темы, общая для всех подсказок, от 0 до 1; 0, если выдачу получить не удалось.
cpc — оценка по уровню объёма, как в search_volume.
Первый запрос по ключу занимает 5–10 секунд; повтор из кэша отвечает сразу.

Регионы

POST /v1/keywords/locations показывает, как спрос по ключу распределён по регионам.

Поле	Описание
`keyword`	Ключевое слово, обязательное
`language_code`	Принимается для совместимости, не используется

curl -X POST "https://proxy.seyka.ru/v1/keywords/locations" \
  -H "Authorization: Bearer $SEYKA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keyword": "купить телефон"}'

{
  "tasks": [
    {
      "status_code": 20000,
      "status_message": "Ok.",
      "result": [
        {
          "keyword": "купить телефон",
          "items": [
            {
              "location_code": 1012,
              "location_name": "Moscow",
              "location_name_local": "Москва",
              "country_code": "RU",
              "search_volume": 1216999,
              "share": 0.0625,
              "affinity_index": 103.15
            }
          ]
        }
      ]
    }
  ]
}

Регионы без кода DataForSEO получают location_code, равный коду региона Яндекса плюс 10000.

Кэш

Ответы кэшируются: повтор того же запроса в пределах окна кэша оплачивается по цене повтора из кэша, попадание показывает заголовок X-Cache: HIT.

Ошибки

400 — пустые keywords или keyword, больше 100 ключей.
403 — исчерпана квота Wordstat у источника.
429 — Wordstat ограничил частоту запросов; повторите позже.
503 — сервис Wordstat не настроен или недоступен.
500 — сбой запроса к Wordstat, в том числе запрос, который Wordstat отклонил.

Остальные коды — в разделе Ошибки.

Миграция с DataForSEO

https://api.dataforseo.com/v3/keywords_data/…/search_volume/live
https://proxy.seyka.ru/v1/keywords/search_volume

Формат ответа совпадает по конверту и основным полям. Запрос — один объект, а не массив задач, как у DataForSEO.

Цена

Каждый вызов оплачивается отдельно, повтор из кэша — дешевле. Ставки — на странице Цены.