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

`gruppirovka` Группировка запросов по ТОП-10 Яндекса

Собирает ТОП-10 Яндекса по каждому запросу и объединяет в группу запросы, у которых в выдаче достаточно общих URL. Метод асинхронный: POST ставит задачу и возвращает report_id, по нему GET отдаёт результат. То же, что инструмент Группировка запросов по ТОПу.

Стоимость: 2 лимита за запрос, 4 — со сбором частот (ws_queries)
Режим: асинхронный: report_id
Запросов за задачу: от 2 до 10 000 (после удаления дублей)
Поисковая система: только Яндекс

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

POST /api/gruppirovka

Задача встаёт в очередь, лимиты списываются сразу при постановке. Пустые строки и точные повторы из requests отбрасываются до подсчёта количества и стоимости.

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

key string обязательный

Ключ API из настроек аккаунта. Всегда в query-строке, в том числе у POST.
requests array обязательный

Запросы, каждый отдельным элементом: requests[]=…&requests[]=…. Строка с переводами строк не принимается — только массив.
lr int

Регион Яндекса, например 213 — Москва.

По умолчанию 213
method string

Алгоритм группировки. hard — у всех запросов группы должны быть одни и те же общие URL; middle — цепочкой: достаточно пересечения с любым запросом группы; soft — достаточно пересечения с первым запросом группы. Любое другое значение, в том числе числа, работает как hard.

soft
мягкая

middle
средняя

hard
жёсткая

По умолчанию hard
degree_group int

Степень группировки: сколько общих URL в ТОП-10 нужно, чтобы запросы попали в одну группу.

По умолчанию 3
ws_queries int

Собрать частоты Вордстата. Тогда группа называется запросом с наибольшей точной частотой, а стоимость растёт до 4 лимитов за запрос.

1
собирать частоты

Ответ

report_id int

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

POST /api/gruppirovka

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

<?php
$url = 'https://tools.pixelplus.ru/api/gruppirovka?' . 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,
        'degree_group' => 3,
    ]),
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

print_r($response);

import requests

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

requests обязательный Запросы, каждый отдельным элементом: requests[]=…&requests[]=… · по одному на строку lr Регион Яндекса, например 213 — Москва degree_group Степень группировки: сколько общих URL в ТОП-10 нужно, чтобы запросы попали в одну группу

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

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

{
    "report_id": 2617068
}

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

GET /api/gruppirovka

Пока задача в работе, приходит {"error":"In progress","code":50}, а после старта обработки — ещё процент готовности. Обычно группировка занимает несколько минут, большое ядро — до получаса: опрашивайте раз в 30–60 секунд.

Параметры query

key string обязательный

Ключ API из настроек аккаунта. Всегда в query-строке, в том числе у POST.
report_id int обязательный

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

Ответ

Объект с полями time и cost и пронумерованными с нуля парами «запрос — группа». Группа называется по первому запросу в ней; запрос, ни с чем не сгруппированный, образует группу из себя самого.

time int

Время завершения задачи, Unix timestamp.
cost int

Стоимость задачи в лимитах.
0, 1, 2… object

Запрос и его группа.
Вложенные поля
- request string
  
  Запрос.
- group string
  
  Название группы.

GET /api/gruppirovka

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

<?php
$url = 'https://tools.pixelplus.ru/api/gruppirovka?' . 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/gruppirovka",
    params={
        "key": "ВАШ_КЛЮЧ",
        "report_id": 2617068,
    },
    timeout=60,
)
print(response.json())

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

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

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

{
    "time": 1759740000,
    "cost": 6,
    "0": {
        "request": "купить диван",
        "group": "купить диван"
    },
    "1": {
        "request": "диван купить в москве",
        "group": "купить диван"
    },
    "2": {
        "request": "угловой диван цена",
        "group": "угловой диван цена"
    }
}

Ошибки

Код	Сообщение	Когда
`50`	`In progress`	Задача ещё выполняется. Когда обработка началась, в ответе есть `progress` (проценты) и `time`.
`-50`	`Empty requests`	POST без `requests`.
`-66`	`Not enough requests`	После удаления пустых строк и повторов осталось меньше 2 запросов.
`-67`	`To much requests`	Больше 10 000 запросов.
`-60`	`To many tasks from one user. Try again later.`	У пользователя уже больше 5 незавершённых задач группировки.
`-65`	`Empty report id`	GET без `report_id`.
`-4`	`Access denied`	`report_id` не существует, принадлежит другому пользователю или другому инструменту.
`-104`	`Processing error`	Задача завершилась с ошибкой. Также `-105` (кончились лимиты), `-106` (отменена), `-107` (дольше 6 часов), `-125` (прочее).
`-68`	`Not enough daily limits`	Не хватает лимитов. Для тарифов с ограничением по периодам — также `-80`, `-81`, `-82`, `-83`; см. ошибки.
`-1`	`Access denied`	Не передан `key`. HTTP-код 404.
`-2`	`Access denied`	Ключ не найден. HTTP-код 403.

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

{
    "error": "In progress",
    "code": 50,
    "progress": 40,
    "time": "2026-10-06 12:00:00"
}

Что не работает через API

Параметры home_pages и rel_url, которые упоминались в прежней документации, метод не использует. Числовые значения method (0–3, «pixeltools») тоже не распознаются: группировка идёт методом hard. Выбрать Google, исключить домены или агрегаторы, как в веб-версии, через API нельзя.

Повторы запросов

Повторы отбрасываются с учётом регистра и пробелов: Диван и диван при постановке считаются разными запросами и оба оплачиваются, хотя в результате совпадут. Нормализуйте список заранее.

gruppirovka Группировка запросов по ТОП-10 Яндекса

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

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

Ответ

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

Параметры query

Ответ

Ошибки

Что не работает через API

Повторы запросов

`gruppirovka` Группировка запросов по ТОП-10 Яндекса