PHPackages                             shanginn/yandex-wordstat - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. shanginn/yandex-wordstat

ActiveLibrary[API Development](/categories/api)

shanginn/yandex-wordstat
========================

A strongly-typed, modern PHP SDK for the Yandex Wordstat API

0.2.1(2mo ago)05MITPHPPHP >=8.2CI passing

Since Mar 1Pushed 2mo agoCompare

[ Source](https://github.com/shanginn/yandex-wordstat-sdk-php)[ Packagist](https://packagist.org/packages/shanginn/yandex-wordstat)[ RSS](/packages/shanginn-yandex-wordstat/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (3)Dependencies (7)Versions (4)Used By (0)

Yandex Wordstat PHP SDK
=======================

[](#yandex-wordstat-php-sdk)

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

Возможности
-----------

[](#возможности)

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

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

[](#документация)

📚 **[Смотреть полную документацию в Wiki](../../wiki)**

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

[](#быстрые-ссылки)

- [Начало работы и обзор REST API](../../wiki/REST-API)
- [/topRequests — Популярные запросы](../../wiki/top-requests)
- [/dynamics — Динамика запросов](../../wiki/dynamics)
- [/regions — Региональная статистика](../../wiki/regions)
- [/userInfo — Информация о пользователе](../../wiki/user-info)
- [/getRegionsTree — Дерево регионов](../../wiki/get-regions-tree)

Установка
---------

[](#установка)

```
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. Информация о пользователе и квоте

[](#1-информация-о-пользователе-и-квоте)

```
$userInfo = $wordstat->userInfo();

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

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

[](#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. Пакетный запрос для нескольких фраз

[](#3-пакетный-запрос-для-нескольких-фраз)

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

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

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

[](#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. Региональная статистика

[](#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. Дерево регионов

[](#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.

**[Подробная инструкция по получению токена →](../../wiki/oauth-token)**

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

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

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

```
export YANDEX_OAUTH_TOKEN=your_oauth_token_here
```

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

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

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

[](#доступные-enum-классы)

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

[](#devicetype--тип-устройства)

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

[](#dynamicsperiod--период-динамики)

ЗначениеОписание`DynamicsPeriod::DAILY`По дням`DynamicsPeriod::WEEKLY`По неделям`DynamicsPeriod::MONTHLY`По месяцам### RegionType — тип региона

[](#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

###  Health Score

35

—

LowBetter than 79% of packages

Maintenance86

Actively maintained with recent releases

Popularity4

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity38

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

3

Last Release

72d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/311e425711f60c09486c23252696fbe4dfa77e9b0dd5517bc89b288ac2f58655?d=identicon)[shanginn](/maintainers/shanginn)

---

Top Contributors

[![shanginn](https://avatars.githubusercontent.com/u/3357943?v=4)](https://github.com/shanginn "shanginn (3 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/shanginn-yandex-wordstat/health.svg)

```
[![Health](https://phpackages.com/badges/shanginn-yandex-wordstat/health.svg)](https://phpackages.com/packages/shanginn-yandex-wordstat)
```

###  Alternatives

[sylius/sylius

E-Commerce platform for PHP, based on Symfony framework.

8.4k5.6M651](/packages/sylius-sylius)[api-platform/symfony

Symfony API Platform integration

323.2M67](/packages/api-platform-symfony)[api-platform/serializer

API Platform core Serializer

223.4M31](/packages/api-platform-serializer)[fschmtt/keycloak-rest-api-client-php

PHP client to interact with Keycloak's Admin REST API.

4684.7k2](/packages/fschmtt-keycloak-rest-api-client-php)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)