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

`serp-yandex-search-and-context` Выдача Яндекса: органика, реклама и колдунщики

Собирает выдачу Яндекса по списку запросов и вместе с органикой отдаёт рекламные блоки — над выдачей, внутри неё и под ней — и признаки колдунщиков. Работает асинхронно, но не через report_id, как остальные инструменты: задача ставится методом searchAndContext/set, готовность проверяется serp/yandex/status, результат забирается serp/yandex/get по task_id.

Режим: асинхронный: task_id → status → get
Стоимость: 2 лимита за запрос с рекламой, 1 — только органика
Запросов в задаче: до 15 000
Методы: GET и POST; ключ — в query

Постановка задачи: органика и реклама

POST /api/serp/yandex/searchAndContext/set

Ставит задачу и сразу списывает лимиты: 2 за каждый уникальный запрос, независимо от deep, is_mobile и ads_only. Параметры можно передать и в query.

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

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

Запросы: строка, по запросу на строку, или массив keywords[]. Пустые строки и дубли отбрасываются. До 15 000 запросов.
region int обязательный

Регион Яндекса (lr), например 213 — Москва. Только из справочника serp/regions/get.
deep int

Сколько результатов органической выдачи собирать по запросу. На стоимость не влияет.

По умолчанию 50
is_mobile int

Мобильная выдача вместо десктопной.

0
десктоп

1
мобильная

По умолчанию 0
ads_only int

Собрать только рекламу, без органической выдачи. Цена та же.

0
органика и реклама

1
только реклама

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

Ответ

task_id int

ID задачи для status и get.

POST /api/serp/yandex/searchAndContext/set

curl -X POST 'https://tools.pixelplus.ru/api/serp/yandex/searchAndContext/set?key=ВАШ_КЛЮЧ' \
  --data-urlencode 'keywords[]=купить смартфон' \
  --data-urlencode 'keywords[]=купить ноутбук' \
  --data-urlencode 'region=213'

<?php
$url = 'https://tools.pixelplus.ru/api/serp/yandex/searchAndContext/set?' . 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([
        'keywords' => [
            'купить смартфон',
            'купить ноутбук',
        ],
        'region' => 213,
    ]),
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

print_r($response);

import requests

response = requests.post(
    "https://tools.pixelplus.ru/api/serp/yandex/searchAndContext/set",
    params={
        "key": "ВАШ_КЛЮЧ",
    },
    data=[
        ("keywords[]", "купить смартфон"),
        ("keywords[]", "купить ноутбук"),
        ("region", 213),
    ],
    timeout=60,
)
print(response.json())

keywords обязательный Запросы: строка, по запросу на строку, или массив keywords[] · по одному на строку region обязательный Регион Яндекса (lr), например 213 — Москва

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

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

{
    "task_id": 18452301
}

Постановка задачи: только органика

POST /api/serp/yandex/set

То же без сбора рекламы — за 1 лимит на запрос; рекламные блоки в результате пустые. Параметры, ответ, статус и получение результата — как у searchAndContext/set, кроме ads_only.

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

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

Запросы: строка, по запросу на строку, или массив keywords[]. Пустые строки и дубли отбрасываются. До 15 000 запросов.
region int обязательный

Регион Яндекса (lr), например 213 — Москва. Только из справочника serp/regions/get.
deep int

Сколько результатов органической выдачи собирать по запросу. На стоимость не влияет.

По умолчанию 50
is_mobile int

Мобильная выдача вместо десктопной.

0
десктоп

1
мобильная

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

POST /api/serp/yandex/set

curl -X POST 'https://tools.pixelplus.ru/api/serp/yandex/set?key=ВАШ_КЛЮЧ' \
  --data-urlencode 'keywords[]=купить смартфон' \
  --data-urlencode 'keywords[]=купить ноутбук' \
  --data-urlencode 'region=213'

<?php
$url = 'https://tools.pixelplus.ru/api/serp/yandex/set?' . 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([
        'keywords' => [
            'купить смартфон',
            'купить ноутбук',
        ],
        'region' => 213,
    ]),
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

print_r($response);

import requests

response = requests.post(
    "https://tools.pixelplus.ru/api/serp/yandex/set",
    params={
        "key": "ВАШ_КЛЮЧ",
    },
    data=[
        ("keywords[]", "купить смартфон"),
        ("keywords[]", "купить ноутбук"),
        ("region", 213),
    ],
    timeout=60,
)
print(response.json())

keywords обязательный Запросы: строка, по запросу на строку, или массив keywords[] · по одному на строку region обязательный Регион Яндекса (lr), например 213 — Москва

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

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

{
    "task_id": 18452302
}

Готовность задачи

POST /api/serp/yandex/status

Опрашивайте раз в 5–10 секунд, пока progress не станет 100. Сразу после постановки может прийти {"error": "session is not ready"} — задача ещё не попала в очередь, повторите запрос.

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

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

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

Ответ

progress int

Готовность, % от 0 до 100.

POST /api/serp/yandex/status

curl -X POST 'https://tools.pixelplus.ru/api/serp/yandex/status?key=ВАШ_КЛЮЧ' \
  --data-urlencode 'task_id=18452301'

<?php
$url = 'https://tools.pixelplus.ru/api/serp/yandex/status?' . 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([
        'task_id' => 18452301,
    ]),
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

print_r($response);

import requests

response = requests.post(
    "https://tools.pixelplus.ru/api/serp/yandex/status",
    params={
        "key": "ВАШ_КЛЮЧ",
    },
    data={
        "task_id": 18452301,
    },
    timeout=60,
)
print(response.json())

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

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

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

{
    "progress": 64
}

Результат

POST /api/serp/yandex/get

Вызывайте, когда progress дошёл до 100. Повторные вызовы бесплатны. Большую задачу читайте частями: увеличивайте offset на limit, пока не придёт пустая выборка.

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

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

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

Сколько запросов отдать за вызов.

По умолчанию 60000
offset int

Смещение для постраничного чтения.

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

Ответ

Список объектов — по одному на запрос задачи. Данные отдаются парсером как есть; кроме описанных полей могут приходить служебные (count_results, parsed_at и др.).

query string

Запрос.
query_id string

Порядковый номер запроса в задаче.
region int

Регион.
is_mobile int

1 — мобильная выдача.
organic[] array

Органика: position, url, domain, title, snippet, visible_link. Пусто при ads_only=1.
ads_top[] array

Реклама над выдачей: position, url, domain, title, snippet.
ads_middle[] array

Реклама внутри выдачи.
ads_bottom[] array

Реклама под выдачей.
koldunshiki object

Колдунщики, true/false: entity_card — карточка объекта, alice_answer — ответ Алисы, facts — факты, see_also — «смотрите также», map — карта, companies — организации, currency_converter — конвертер валют.

POST /api/serp/yandex/get

curl -X POST 'https://tools.pixelplus.ru/api/serp/yandex/get?key=ВАШ_КЛЮЧ' \
  --data-urlencode 'task_id=18452301'

<?php
$url = 'https://tools.pixelplus.ru/api/serp/yandex/get?' . 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([
        'task_id' => 18452301,
    ]),
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

print_r($response);

import requests

response = requests.post(
    "https://tools.pixelplus.ru/api/serp/yandex/get",
    params={
        "key": "ВАШ_КЛЮЧ",
    },
    data={
        "task_id": 18452301,
    },
    timeout=60,
)
print(response.json())

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

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

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

[
    {
        "query": "купить смартфон",
        "query_id": "0",
        "region": 213,
        "is_mobile": 0,
        "source": "yandex",
        "organic": [
            {
                "position": 1,
                "url": "https://www.example-shop.ru/smartfony/",
                "domain": "example-shop.ru",
                "title": "Смартфоны — купить в интернет-магазине",
                "snippet": "Более 2000 моделей смартфонов с доставкой…",
                "visible_link": "example-shop.ru › smartfony"
            }
        ],
        "ads_top": [
            {
                "position": 1,
                "url": "https://ads.example.ru/phones/",
                "domain": "ads.example.ru",
                "title": "Смартфоны со скидкой до 30%",
                "snippet": "Рассрочка 0%. Доставка за 2 часа."
            }
        ],
        "ads_middle": [],
        "ads_bottom": [],
        "koldunshiki": {
            "entity_card": false,
            "alice_answer": false,
            "facts": false,
            "see_also": true,
            "map": false,
            "companies": true,
            "currency_converter": false
        }
    }
]

Справочник регионов

GET /api/serp/regions/get

Регионы, которые принимает параметр region. Ключ не нужен — метод открыт.

Ответ

[].lr int

Код региона Яндекса — значение для region.
[].slug string

Название региона.

GET /api/serp/regions/get

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

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

$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/serp/regions/get",
    params={
        "key": "ВАШ_КЛЮЧ",
    },
    timeout=60,
)
print(response.json())

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

[
    {
        "lr": "213",
        "slug": "Москва"
    },
    {
        "lr": "2",
        "slug": "Санкт-Петербург"
    }
]

Ошибки

Код	Сообщение	Когда
`-50`	`empty keywords`	После очистки не осталось запросов. Тот же код у `too much keywords, current limit 15000` и `wrong region` — региона нет в справочнике.
`-55`	`empty task_id`	`task_id` не передан (у `get` — ещё и не число).
`-75`	`server error`	Задачу не удалось поставить в очередь; лимиты не списаны — повторите запрос.
`—`	`session is not ready`	`status`: задача ещё не появилась в очереди. Не ошибка, повторите запрос.
`-68, -80…-83`	`Not enough … limits`	Не хватает лимитов на задачу; в ответе `available` и `need`. Задача не создаётся.
`-1, -2`	`Access denied`	Ключ не передан или не найден. В отличие от других методов, HTTP-код — 200.

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

{
    "error": "empty keywords",
    "code": -50
}

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

searchAndContext/set — 2 лимита за каждый уникальный запрос, serp/yandex/set — 1. Списание одно — при успешной постановке; status и get бесплатны. Задача на 500 запросов с рекламой спишет 1000 лимитов. Если реклама и колдунщики не нужны, берите serp/yandex/set.

Ограничения

Не больше 15 000 запросов в задаче — больший список разбивайте.
Реклама ротируется: ads_top, ads_middle и ads_bottom — это объявления на момент сбора, а не «средний» набор.
Все методы группы отвечают HTTP 200 и при ошибках — проверяйте поле error.

serp-yandex-search-and-context Выдача Яндекса: органика, реклама и колдунщики

Постановка задачи: органика и реклама

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

Ответ

Постановка задачи: только органика

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

Готовность задачи

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

Ответ

Результат

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

Ответ

Справочник регионов

Ответ

Ошибки

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

Ограничения

`serp-yandex-search-and-context` Выдача Яндекса: органика, реклама и колдунщики