SEOProvision
Два файла с названием result.json могут выглядеть одинаково, хотя один собран по Москве с компьютеров, а второй — по всей России со всех устройств. API Wordstat ускоряет регулярную выгрузку, но без сохранённых параметров быстрее размножает ошибку. Начните с вопроса к данным, а параметры сохраните вместе с ответом.
Сначала выберите вопрос, потом метод
Метод topRequests нужен, когда вы хотите увидеть запросы, связанные с исходной фразой, и оценить состав спроса. Он помогает заметить разные намерения: заказать услугу, узнать цену, выполнить работу самостоятельно или найти конкретный инструмент.
Метод dynamics отвечает на другой вопрос: как менялась частотность во времени. В его ответе важны даты, значение count и относительная доля share. Это временной ряд, а не список формулировок.
Не складывайте ответы двух методов: список формулировок и временной ряд отвечают на разные вопросы и не образуют одну метрику. Сначала запишите цель выгрузки одной фразой: «найти варианты запросов по теме» или «проверить устойчивость спроса за период». Это простое решение определяет endpoint и структуру последующей обработки.
Доступ собирается без токена в исходном коде
Актуальный Wordstat API работает внутри Yandex Search API. Для вызова нужен сервисный аккаунт с подходящей ролью, API-ключ с областью действия сервиса или IAM-токен, а также идентификатор каталога folderId.
Секрет не вставляют в файл, который попадёт в репозиторий. Передайте его через переменную окружения или хранилище секретов среды запуска. В примерах ниже стоят условные значения; заменять их реальным ключом прямо в коде не нужно.
Authorization: Api-key <API_KEY>
Content-Type: application/json
Перед первым рабочим запуском проверьте права на тестовой фразе. Ошибка авторизации должна останавливать задачу, а не создавать пустой JSON, который следующий этап примет за отсутствие спроса.
Топ запросов начинается с минимального POST
Для первого вызова достаточно фразы, идентификаторов регионов, типов устройств и folderId. Москва в Wordstat имеет идентификатор 213; для другого рынка подставьте подходящий регион, а не копируйте значение вслепую.
{
"phrase": "seo аудит сайта",
"regions": ["213"],
"devices": ["DEVICE_ALL"],
"folderId": "<FOLDER_ID>"
}
Тело отправляют POST-запросом к методу topRequests. В ответе сохраняйте не только частотность, но и саму формулировку. Если скрипт оставит одни числа, вы не сможете понять, какие намерения были объединены и почему итог изменился.
Начните с одной фразы и откройте ответ глазами: на месте ли поля, не испортилась ли кириллица, чем обозначен пустой результат. Только после этого добавляйте список фраз и параллельные задачи. Так ошибка в одном преобразовании не размножится на всю семантику.
Динамика требует границ периода
Для dynamics укажите тип агрегации, начало и конец интервала. Официальный метод поддерживает дневной, недельный и месячный период. При недельной агрегации начало должно приходиться на понедельник, а окончание — на воскресенье; для месяца используются его первый и последний день.
{
"phrase": "seo аудит сайта",
"period": "PERIOD_WEEKLY",
"fromDate": "2026-06-01T00:00:00Z",
"toDate": "2026-06-28T00:00:00Z",
"regions": ["213"],
"devices": ["DEVICE_DESKTOP"],
"folderId": "<FOLDER_ID>"
}
Для недельной и месячной детализации не переносите сложную строку операторов из ручного Wordstat: метод поддерживает там только оператор «+». Полный набор операторов доступен при детализации по дням. Если это ограничение проигнорировать, запрос не станет «примерно правильным» — его контракт уже другой.
В ответе связывайте каждое значение count с датой. Поле share помогает оценивать долю фразы в общем объёме запросов за тот же отрезок, но не заменяет абсолютное значение. Для сравнения рядов оставляйте одинаковыми регионы, устройства, оператор и период агрегации.
Лимиты обрабатывают паузой, а не циклом
HTTP 429 означает, что запросы упёрлись в доступный лимит. HTTP 503 может указывать на исчерпание общей квоты или временную недоступность сервиса. Немедленный повтор в бесконечном цикле только увеличивает нагрузку и скрывает исходную проблему.
- Сохраните код ответа и текст ошибки.
- Если сервис сообщил время пополнения лимита, дождитесь его.
- Для временного сбоя увеличивайте паузу между попытками.
- Ограничьте число повторов и завершите задачу с явной ошибкой.
- Не повторяйте автоматически ошибки авторизации и неверного тела запроса.
После HTTP 200 проверьте ожидаемый массив и обязательные поля каждой записи. Иначе HTML ошибки или изменённая структура ответа могут попасть в хранилище под видом нормальной выгрузки. Проверьте структуру до записи итогового файла. Пустой ответ храните как отдельное состояние, а не как нулевую частотность.
Паспорт выгрузки важнее имени файла
Рядом с данными сохраните короткий паспорт. Он превращает выгрузку из анонимного файла в воспроизводимый замер:
- метод и endpoint;
- исходная фраза и оператор;
- regions и devices;
- period, fromDate и toDate для динамики;
- время запроса, HTTP-статус и число попыток;
- версия скрипта, который преобразовал ответ.
Сравнивать две выгрузки можно после проверки этих полей. Если регионы или период различаются, расхождение не доказывает изменение спроса. Сначала повторите запрос с одинаковым контрактом.
API решает задачу доставки данных, но не выбирает намерение, структуру страницы и приоритет темы. SEOProvision связывает выгрузку с аналитикой и контентом, когда ведёт комплексное SEO-продвижение сайта.
Интеграция готова, если коллега без устных подсказок повторяет POST по паспорту и получает сопоставимый результат. Скорость без этой проверки лишь быстрее производит файлы, которым нельзя доверять.