Инструменты · key

`wordstatapi` Частоты запросов из Вордстата

Собирает частоты Яндекс Вордстата для списка запросов: общую, точную, в кавычках и с фиксированным порядком слов — по одному или нескольким регионам. Дополнительно считает годовую частоту и её разбивку по месяцам. Метод асинхронный: постановка возвращает report_id, результат забирается по нему. То же в интерфейсе — сбор частот и запросов из Вордстата.

Режим: асинхронный: report_id
Запросов в задаче: до 10 000
Стоимость: 1 лимит за каждую частоту по каждому запросу и региону; списывается после выполнения
Параллельно: до 5 задач

Постановка задачи

POST /api/wordstatapi

Параметры задачи передаются в теле формы, ключ — в query. Если не выбран ни один тип частоты, собирается общая (overall).

Параметры query и тело формы

requests array обязательный

Запросы: массив requests[] или строка, по запросу на строку. До 10 000 штук, длина запроса с минус-словами — до 250–3000 символов в зависимости от источника данных.
lr array обязательный

Регионы Яндекса: массив lr[], можно несколько. all — без привязки к региону.
device string

Тип устройств. Любое другое значение, в том числе all, — все устройства.

desktop
десктопы

mobile
мобильные
overall int

1 — общая частота (слово запроса без операторов).
exact int

1 — точная частота ("!слово !слово").
quoted int

1 — частота в кавычках.
fixed int

1 — точная частота с фиксированным порядком слов. В ответе — поле exact_fixed.
delete_special_characters int

1 — убрать спецсимволы из запросов.
delete_zero_keywords int

1 — убрать из ответа запросы с нулевой общей или точной частотой.
frequency_relations int

1 — посчитать отношение точной частоты к общей.
cb_total_annual int

1 — годовая частота: сумма общей частоты за 12 месяцев.
cb_total_annual_by_month int

1 — годовая частота с разбивкой по месяцам.
cb_total_annual_by_month_type int

За сколько месяцев отдать помесячную разбивку. Другие значения заменяются на 12.

12
12 месяцев

24
24 месяца

По умолчанию 12

Ответ

report_id int

ID задачи для получения результата.

POST /api/wordstatapi

curl -X POST 'https://tools.pixelplus.ru/api/wordstatapi?key=ВАШ_КЛЮЧ' \
  --data-urlencode 'requests[]=купить диван' \
  --data-urlencode 'requests[]=диван угловой' \
  --data-urlencode 'lr[]=213' \
  --data-urlencode 'overall=1' \
  --data-urlencode 'exact=1'

<?php
$url = 'https://tools.pixelplus.ru/api/wordstatapi?' . http_build_query([
    'key' => 'ВАШ_КЛЮЧ',
]);

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 60,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => http_build_query([
        'requests' => [
            'купить диван',
            'диван угловой',
        ],
        'lr' => [
            213,
        ],
        'overall' => 1,
        'exact' => 1,
    ]),
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

print_r($response);

import requests

response = requests.post(
    "https://tools.pixelplus.ru/api/wordstatapi",
    params={
        "key": "ВАШ_КЛЮЧ",
    },
    data=[
        ("requests[]", "купить диван"),
        ("requests[]", "диван угловой"),
        ("lr[]", 213),
        ("overall", 1),
        ("exact", 1),
    ],
    timeout=60,
)
print(response.json())

requests обязательный Запросы: массив requests[] или строка, по запросу на строку · по одному на строку lr обязательный Регионы Яндекса: массив lr[], можно несколько · по одному на строку overall 1 — общая частота (слово запроса без операторов) exact 1 — точная частота ("!слово !слово")

Запрос настоящий — выполнится с вашим ключом

Пример ответа

{
    "report_id": 2617068
}

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

GET /api/wordstatapi

Пока задача выполняется, приходит {"error": "In progress", "code": 50}. Готовый результат — объект: запрос → регион → частоты.

Параметры query

report_id int обязательный

ID задачи из ответа на постановку.

Ответ

Частота, которую не заказывали, равна -1.

{запрос}.{регион}.from string

Откуда запрос: Исходная фраза.
{запрос}.{регион}.overall int

Общая частота.
{запрос}.{регион}.exact int

Точная частота.
{запрос}.{регион}.quoted int

Частота в кавычках.
{запрос}.{регион}.exact_fixed int

Точная частота с фиксированным порядком слов.
{запрос}.{регион}.frequency_relations float

Точная / общая, два знака; 0, если одна из частот нулевая.
{запрос}.{регион}.total_annual int

Только с годовой частотой: сумма за период.
{запрос}.{регион}.by_month object

Только с годовой частотой: дата начала месяца (ДД.ММ.ГГГГ) → частота.
{запрос}.{регион}.by_periods object

Только с годовой частотой: суммы last_12_months и previous_12_months.
periods object

Границы периодов last_12_months и previous_12_months; пустой массив без годовой частоты.

GET /api/wordstatapi

curl -G 'https://tools.pixelplus.ru/api/wordstatapi' \
  --data-urlencode 'key=ВАШ_КЛЮЧ' \
  --data-urlencode 'report_id=2617068'

<?php
$url = 'https://tools.pixelplus.ru/api/wordstatapi?' . http_build_query([
    'key' => 'ВАШ_КЛЮЧ',
    'report_id' => 2617068,
]);

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 60,
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

print_r($response);

import requests

response = requests.get(
    "https://tools.pixelplus.ru/api/wordstatapi",
    params={
        "key": "ВАШ_КЛЮЧ",
        "report_id": 2617068,
    },
    timeout=60,
)
print(response.json())

report_id обязательный ID задачи из ответа на постановку

Запрос настоящий — выполнится с вашим ключом

Пример ответа

{
    "купить диван": {
        "213": {
            "from": "Исходная фраза",
            "overall": 156533,
            "exact": 12330,
            "quoted": 14214,
            "exact_fixed": -1,
            "frequency_relations": -1
        }
    },
    "диван угловой": {
        "213": {
            "from": "Исходная фраза",
            "overall": 73022,
            "exact": 4123,
            "quoted": 5120,
            "exact_fixed": -1,
            "frequency_relations": -1
        }
    },
    "periods": []
}

Ошибки

Код	Сообщение	Когда
`-50`	`{поле: описание}`	Ошибки параметров: в `error` — объект «поле → сообщение» (`requests`, `lr`, `requests_count` — больше 10 000 запросов, `limits` — не хватает лимитов на оценку стоимости). Запрос не методом POST — `["Data not set"]`.
`-60`	`To many tasks from one user. Try again later. Launched 5 threads out of 5`	Уже идут 5 задач этого метода.
`50`	`In progress`	Задача ещё выполняется.
`-4`	`Access denied`	`report_id` чужой или от другого инструмента.
`-104…-107, -125`	`Processing error / Limits run out / …`	Задача завершилась ошибкой — см. асинхронные задачи.
`-68, -80…-83`	`Not enough … limits`	Исчерпан дневной, часовой, недельный, месячный или годовой лимит.
`-1, -2`	`Access denied`	Ключ не передан (HTTP 404) или не найден (HTTP 403).

Ответ с ошибкой

{
    "error": {
        "requests": "Поле «Список поисковых запросов» не может быть пустым",
        "lr": "Необходимо выбрать регион для анализа"
    },
    "code": -50
}

Сколько стоит

При постановке лимиты не списываются, а только проверяется, хватит ли их на оценку: запросы × число выбранных частот × регионы, а с годовой частотой — ещё +5 к множителю частот. Фактический расход списывается после выполнения: 1 лимит за каждую частоту каждого запроса в каждом регионе, годовая частота — 5 лимитов за запрос в регионе.

Регионы передавайте массивом lr[], даже если регион один: строка lr=213 ломает оценку стоимости.

Запросы сравниваются после очистки: двойные пробелы и лишние символы убираются, дубли схлопываются — ключи в ответе могут отличаться от переданных строк. Запросы без данных Вордстата в ответ не попадают.

Нужно расширить семантику, а не проверить готовый список — используйте wordstatapikeywords.

wordstatapi Частоты запросов из Вордстата

Постановка задачи

Параметры query и тело формы

Ответ

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

Параметры query

Ответ

Ошибки

Сколько стоит

`wordstatapi` Частоты запросов из Вордстата