API: Получение данных Яндекс.Вордстат

API позволяет получить статистику по ключевым словам из сервиса Яндекс.Вордстат через инструмент PR-CY.
Можно собирать частотность по нескольким регионам и типам сразу, похожие и включающие фразы, а также сезонность — помесячную динамику запросов за период.

Перед началом: получите API-ключ в настройках.

Логика работы API

1. Создать задачу — отправляем POST-запрос с ключевыми словами, регионами и типами частотности.
2. В ответ получаем ID задачи.
3. Получить результат — отправляем GET-запрос по ID задачи.
4. В ответе возвращаются данные Wordstat.

1. Создание задачи

POST:

https://apis.pr-cy.ru/api/v2.1.0/tool-tasks/

Параметры запроса

Поддерживаемые значения types

Как узнать код региона

curl --globoff 'https://apis.pr-cy.ru/api/v2.1.0/regions?filter[search]=Москва&page[limit]=5' \
  --header 'Api-Key: ВАШ_КЛЮЧ'

В ответе берите поле yandexKey — это и есть код региона для regions (Москва — 213).

Пример запроса

curl 'https://apis.pr-cy.ru/api/v2.1.0/tool-tasks/' \
  --header 'Content-Type: application/vnd.api+json' \
  --header 'Api-Key: ВАШ_КЛЮЧ' \
  --data-raw '{
    "data": {
      "type": "toolTasks",
      "attributes": {
        "toolName": "wordstatChecker",
        "params": {
          "keywords": ["купить слона", "сколько стоит слон"],
          "types": ["general", "exact"],
          "regions": [213],
          "needRelatedPhrases": true,
          "needIncludingPhrases": true,
          "engine": "yandex"
        }
      }
    }
  }'

2. Проверка сезонности

Сезонность — это не отдельный метод, а параметр seasonality того же инструмента. Он возвращает частотность по месяцам за указанный период.

Период — не больше 24 месяцев.

curl 'https://apis.pr-cy.ru/api/v2.1.0/tool-tasks/' \
  --header 'Content-Type: application/vnd.api+json' \
  --header 'Api-Key: ВАШ_КЛЮЧ' \
  --data-raw '{
    "data": {
      "type": "toolTasks",
      "attributes": {
        "toolName": "wordstatChecker",
        "params": {
          "keywords": ["купить елку"],
          "types": ["general"],
          "regions": [213],
          "seasonality": {
            "start": "2025-07-01",
            "end": "2025-12-31",
            "device": "desktop"
          }
        }
      }
    }
  }'

3. Ответ при создании задачи

API вернёт ID задачи:

{
  "data": {
    "type": "toolTasks",
    "id": "2a67cb477beceb3a677bcf1592214e24",
    "attributes": {..}
  }
}

4. Получение результатов

GET:

https://apis.pr-cy.ru/api/v2.1.0/tool-tasks/{task_id}?filter[since]=0&include=tests

Пример запроса

curl --location --globoff \
'https://apis.pr-cy.ru/api/v2.1.0/tool-tasks/62b55f1b3f2d430123456789abcdef12?filter[since]=0&include=tests' \
  --header 'Content-Type: application/vnd.api+json' \
  --header 'Api-Key: ВАШ_КЛЮЧ'

Где:

• {task_id} — ID задачи, полученный в шаге 1.
• filter[since]=0 — фильтр по времени (0 = с начала).
• include=tests — выдаёт подробный результат.

Повторяйте запрос, пока isUpdating не станет false. После этого данные готовы.

Что приходит в ответе

Результат лежит в included[].attributes.results:

regionId: null означает частотность без учёта региона.

{
  "wordstat": [
    {
      "keyword": "купить елку",
      "values": [
        { "type": "general", "regionId": 213, "count": 5304 }
      ]
    }
  ],
  "seasonality": [
    {
      "keyword": "купить елку",
      "regionId": 213,
      "data": [
        { "date": "2025-07", "count": 2278 },
        { "date": "2025-08", "count": 2347 },
        { "date": "2025-09", "count": 2579 },
        { "date": "2025-10", "count": 7997 },
        { "date": "2025-11", "count": 13748 },
        { "date": "2025-12", "count": 26636 }
      ]
    }
  ],
  "seasonalityMonths": ["2025-07", "2025-08", "2025-09", "2025-10", "2025-11", "2025-12"],
  "seasonalityDevice": "desktop"
}

5. Сколько спишется лимитов

Одна проверка — это пара «фраза + регион + тип частотности». Сезонность добавляет ещё по одной проверке на каждую пару «фраза + регион».

Стоимость задачи можно узнать заранее, без запуска:

curl 'https://apis.pr-cy.ru/api/v2.1.0/tool-tasks/cost' \
  --header 'Content-Type: application/vnd.api+json' \
  --header 'Api-Key: ВАШ_КЛЮЧ' \
  --data-raw '{
    "data": {
      "type": "toolTasks",
      "attributes": {
        "toolName": "wordstatChecker",
        "params": {
          "keywords": ["купить елку"],
          "types": ["general"],
          "regions": [213],
          "seasonality": { "start": "2025-07-01", "end": "2025-12-31" }
        }
      }
    }
  }'

В ответе придёт attributes.cost — сколько лимитов спишется при запуске.

Итого

1. POST /tool-tasks/       toolName "wordstatChecker", params: keywords, types, regions
   (опции: needRelatedPhrases, needIncludingPhrases, seasonality)   → получили id
2. GET  /tool-tasks/{id}?include=tests                              → ждём isUpdating: false
3. Читаем results:
   - wordstat                 → частотность по типам и регионам
   - relatedPhrasesWordstat   → похожие фразы
   - includingPhrasesWordstat → популярные фразы с вхождением
   - seasonality              → помесячная динамика

Смежные инструкции

• Как настроить проверку позиций