README

Строго типизированный, современный PHP SDK для нового REST API Яндекс Wordstat. Построен на amphp/http-client для высокой производительности и crell/serde для надёжной сериализации объектов.

Возможности

Полное покрытие API: поддерживает эндпоинты /getRegionsTree, /topRequests, /dynamics, /regions и /userInfo.
Строгая типизация: типизированные объекты ответов и enum-параметры.
Гибкая фильтрация: фильтрация по регионам, устройствам и временным периодам через удобные enum-классы.
Пакетные запросы: поддержка нескольких фраз в одном запросе к /topRequests.
Пользовательские исключения: чистая обработка ошибок с маппингом на структуры ошибок Yandex API, включая автоматическое определение Rate Limit.

Документация

📚 Смотреть полную документацию в Wiki

Быстрые ссылки

Установка

composer require shanginn/yandex-wordstat

Начало работы

Инициализация

use Shanginn\YandexWordstat\WordstatClient;
use Shanginn\YandexWordstat\YandexWordstat;

$client = new WordstatClient(getenv('YANDEX_OAUTH_TOKEN'));
$wordstat = new YandexWordstat($client);

1. Информация о пользователе и квоте

$userInfo = $wordstat->userInfo();

echo "Логин: {$userInfo->userInfo->login}\n";
echo "Осталось запросов: {$userInfo->userInfo->dailyLimitRemaining} / {$userInfo->userInfo->dailyLimit}\n";

2. Популярные запросы

use Shanginn\YandexWordstat\Enums\DeviceType;

$result = $wordstat->topRequests(
    'яндекс',
    regions: [213, 2], // Москва и Санкт-Петербург
    devices: [DeviceType::PHONE],
);

echo "Всего запросов: {$result->totalCount}\n";
foreach ($result->topRequests as $req) {
    echo "{$req->phrase} — {$req->count} показов\n";
}

3. Пакетный запрос для нескольких фраз

// При передаче массива возвращается TopRequestsResult[]
$results = $wordstat->topRequests(['яндекс', 'гугл', 'mail']);

foreach ($results as $result) {
    echo "Фраза: {$result->requestPhrase}, показов: {$result->totalCount}\n";
}

4. Динамика запросов

use Shanginn\YandexWordstat\Enums\DynamicsPeriod;

$dynamics = $wordstat->dynamics(
    phrase: 'яндекс',
    period: DynamicsPeriod::MONTHLY,
    fromDate: '2025-01-01',
    toDate: '2025-03-31',
);

foreach ($dynamics->dynamics as $item) {
    echo "Дата: {$item->date} | Показы: {$item->count} | Доля: {$item->share}%\n";
}

5. Региональная статистика

use Shanginn\YandexWordstat\Enums\RegionType;

$regionsInfo = $wordstat->regions('яндекс', regionType: RegionType::CITIES);

foreach ($regionsInfo->regions as $region) {
    echo "Регион ID: {$region->regionId} | Показы: {$region->count} | Индекс интереса: {$region->affinityIndex}\n";
}

6. Дерево регионов

$tree = $wordstat->getRegionsTree();

foreach ($tree as $country) {
    echo "Страна: {$country['name']} (ID: {$country['id']})\n";
    foreach ($country['children'] as $region) {
        echo "  Регион: {$region['name']} (ID: {$region['id']})\n";
    }
}

Аутентификация

Для работы с SDK необходим OAuth-токен Яндекса с доступом к Wordstat API.

Подробная инструкция по получению токена →

Краткий порядок действий:

Создайте приложение на https://oauth.yandex.ru/client/new, выбрав доступ Использование API Вордстата.
Подайте заявку на доступ к API в поддержку Яндекс Директа, указав логин и Client ID приложения.
Авторизуйтесь по ссылке https://oauth.yandex.ru/authorize?response_type=token&client_id=<client_id> и сохраните выданный токен.

Установите переменную окружения:

export YANDEX_OAUTH_TOKEN=your_oauth_token_here

Проверить токен можно прямым curl-запросом:

curl -XPOST \
  -H 'Content-type: application/json;charset=utf-8' \
  -H 'Authorization: Bearer <your_oauth_token>' \
  -d '{"phrase":"яндекс","regions":[213,2],"devices":["phone"]}' \
  https://api.wordstat.yandex.net/v1/topRequests

Доступные enum-классы

DeviceType — тип устройства

Значение	Описание
`DeviceType::ALL`	Все устройства
`DeviceType::DESKTOP`	Компьютеры
`DeviceType::MOBILE`	Мобильные устройства
`DeviceType::PHONE`	Телефоны
`DeviceType::TABLET`	Планшеты

DynamicsPeriod — период динамики

Значение	Описание
`DynamicsPeriod::DAILY`	По дням
`DynamicsPeriod::WEEKLY`	По неделям
`DynamicsPeriod::MONTHLY`	По месяцам

RegionType — тип региона

Значение	Описание
`RegionType::ANY`	Любые регионы
`RegionType::CITIES`	Города
`RegionType::REGIONS`	Регионы
`RegionType::EVERYWHERE`	Везде

Обработка ошибок

use Shanginn\YandexWordstat\Exceptions\WordstatRateLimitException;
use Shanginn\YandexWordstat\Exceptions\WordstatApiErrorException;
use Shanginn\YandexWordstat\Exceptions\WordstatException;

try {
    $result = $wordstat->topRequests('яндекс');
} catch (WordstatRateLimitException $e) {
    // Превышен лимит запросов (HTTP 429)
    echo "Лимит запросов превышен. Повторите позже.\n";
} catch (WordstatApiErrorException $e) {
    // Ошибка API (HTTP 4xx/5xx)
    echo "Ошибка API [{$e->getStatusCode()}]: {$e->getMessage()}\n";
} catch (WordstatException $e) {
    // Общая ошибка SDK
    echo "Ошибка: {$e->getMessage()}\n";
}

Запуск тестов

composer install
./vendor/bin/phpunit

Лицензия

MIT

shanginn / yandex-wordstat

Maintainers

Details