Документация на метод "serp-yandex-search-and-context"

Как это работает

• 1 Ставим задачу — передаём список запросов и регион в searchAndContext/set. В ответ приходит task_id. Лимиты списываются в момент создания задачи.
• 2 Ждём готовности — периодически (раз в 5–10 секунд) опрашиваем serp/yandex/status, пока progress не станет равным 100.
• 3 Забираем результат — вызываем serp/yandex/get с тем же task_id. Большие выборки читаем постранично через limit и offset.

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

/api/serp/yandex/searchAndContext/set — принимает GET и POST.

Ответ

{
  "task_id": 18452301
}

2Проверка статуса

/api/serp/yandex/status — общий для всех задач Яндекса метод проверки прогресса.

Ответ

{
  "progress": 64
}

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

/api/serp/yandex/get — вызывается после того, как progress достиг 100.

Структура ответа

Результат — набор объектов, по одному на каждый запрос задачи. Ключевые поля:

Пример результата

[
  {
    "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": [
      {
        "position": 1,
        "url": "https://shop2.example.ru/",
        "domain": "shop2.example.ru",
        "title": "Смартфоны в наличии",
        "snippet": "Официальная гарантия 2 года."
      }
    ],
    "koldunshiki": {
      "entity_card": false,
      "alice_answer": false,
      "facts": false,
      "see_also": true,
      "map": false,
      "companies": true,
      "currency_converter": false
    }
  }
]

Тарификация

Например, задача на 500 запросов спишет 1000 лимитов независимо от значений deep, is_mobile и ads_only. Если доступных лимитов не хватает, задача не создаётся, а в ответе приходит код ошибки и точные значения available / need.

Коды ошибок

Пример ответа при нехватке лимитов

{
  "error": "Not enough daily limits",
  "code": "-68",
  "available": 340,
  "need": 1000
}

Примеры

cURL

curl -X POST 'https://tools.pixelplus.ru/api/serp/yandex/searchAndContext/set?key={ключ-api}' \
  --data-urlencode 'keywords=купить смартфон
купить ноутбук' \
  -d 'region=213' \
  -d 'deep=50' \
  -d 'is_mobile=0'

PHP

<?php

$key = '{ключ-api}';
$base = 'https://tools.pixelplus.ru/api';

function apiPost(string $url, array $data = []): array
{
    $curl = curl_init();
    curl_setopt_array($curl, [
        CURLOPT_URL => $url,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => http_build_query($data),
        CURLOPT_TIMEOUT => 120,
    ]);
    $response = curl_exec($curl);
    curl_close($curl);

    return json_decode($response, true) ?: [];
}

// 1. Ставим задачу
$task = apiPost("{$base}/serp/yandex/searchAndContext/set?key={$key}", [
    'keywords'  => implode("\n", ['купить смартфон', 'купить ноутбук']),
    'region'    => 213,
    'deep'      => 50,
    'is_mobile' => 0,
]);

if (empty($task['task_id'])) {
    exit('Ошибка: ' . ($task['error'] ?? 'unknown'));
}

$taskId = $task['task_id'];

// 2. Ждём готовности
do {
    sleep(10);
    $status = apiPost("{$base}/serp/yandex/status?key={$key}", ['task_id' => $taskId]);
    $progress = (int)($status['progress'] ?? 0);
} while ($progress < 100);

// 3. Забираем результат
$result = apiPost("{$base}/serp/yandex/get?key={$key}", [
    'task_id' => $taskId,
    'limit'   => 60000,
    'offset'  => 0,
]);

print_r($result);

Python

import time
import requests

KEY = '{ключ-api}'
BASE = 'https://tools.pixelplus.ru/api'

task = requests.post(
    f'{BASE}/serp/yandex/searchAndContext/set',
    params={'key': KEY},
    data={
        'keywords': '\n'.join(['купить смартфон', 'купить ноутбук']),
        'region': 213,
        'deep': 50,
        'is_mobile': 0,
    },
).json()

task_id = task['task_id']

while True:
    status = requests.post(
        f'{BASE}/serp/yandex/status',
        params={'key': KEY}, data={'task_id': task_id},
    ).json()
    if status.get('progress', 0) >= 100:
        break
    time.sleep(10)

result = requests.post(
    f'{BASE}/serp/yandex/get',
    params={'key': KEY},
    data={'task_id': task_id, 'limit': 60000, 'offset': 0},
).json()

print(result)

Ограничения и рекомендации

• Не более 15 000 запросов в одной задаче; при большем объёме разбивайте список на несколько задач.
• Запросы внутри задачи дедуплицируются — платить дважды за один и тот же запрос не придётся.
• Опрашивайте статус не чаще одного раза в 5 секунд: задача с тысячами запросов выполняется минутами.
• Результат читается постранично: при больших задачах увеличивайте offset с шагом limit, пока не получите пустую выборку.
• Реклама в Яндексе ротируется, поэтому состав ads_top / ads_bottom отражает выдачу на момент сбора, а не «средний» набор объявлений.
• Регион задаётся кодом lr — коды, которых нет в справочнике /api/serp/regions/get, отклоняются.