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

`geo` Проверка геозависимости запросов

Определяет, геозависим ли запрос: ищет топоним региона в заголовках и сниппетах ТОП-50 Яндекса и считает, какая доля выдачи им локализована. По желанию добавляет коммерциализацию запросов. Метод асинхронный: POST ставит задачу и возвращает report_id, по нему результат забирается GET-запросом. Веб-версия — инструмент «Геозависимость запросов».

Режим: асинхронный: report_id
Стоимость: 1 лимит за запрос, списывается при постановке задачи
Нужно на балансе: 2 лимита на запрос
Одновременно: не больше 6 активных задач

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

POST /api/geo

Принимает список запросов и регион, ставит задачу в очередь и сразу отвечает её номером. Параметры задачи читаются из тела запроса; key — из query-строки.

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

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

Ключ API из настроек аккаунта. Передаётся в query-строке и у POST-запроса тоже.
requests array обязательный

Запросы для проверки: массив requests[] или одна строка, где запросы разделены переводом строки \r\n (строка очищается от пустых строк и дублей).
lr int

Регион Яндекса, код lr. Его название и синонимы и ищутся в выдаче.

По умолчанию 213
deep int

Сколько позиций ТОПа анализировать, от 1 до 50. Значение вне диапазона заменяется на 50.

По умолчанию 50
intent bool

Добавить в ответ коммерциализацию запросов (блок data). Включается любым непустым значением — даже строкой false; чтобы выключить, не передавайте параметр.

По умолчанию false
search_system string

Поисковая система. Неизвестное значение заменяется на yandex.
Сейчас google принимается, но не учитывается: проверка всегда идёт по выдаче Яндекса, и стоимость считается как для Яндекса.

yandex
Яндекс

google
Google

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

Ответ

report_id int

Номер задачи — передайте его в получение результата.

POST /api/geo

curl -X POST 'https://tools.pixelplus.ru/api/geo?key=ВАШ_КЛЮЧ' \
  --data-urlencode 'requests[]=мебель' \
  --data-urlencode 'requests[]=офисная мебель купить' \
  --data-urlencode 'lr=213'

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

print_r($response);

import requests

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

requests обязательный Запросы для проверки: массив requests[] или одна строка, где запросы разделены переводом строки \r\n (строка очищается от пустых строк и дублей) · по одному на строку lr Регион Яндекса, код lr

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

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

{
    "report_id": 18736512
}

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

GET /api/geo

Пока задача выполняется, метод отвечает ошибкой 50 «In progress» — повторите запрос позже. Готовый результат хранится в истории инструмента, его можно забирать повторно.

Параметры query

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

Ключ API из настроек аккаунта. Передаётся в query-строке и у POST-запроса тоже.
report_id int обязательный

Номер задачи из ответа на постановку.

Ответ

request object

Параметры задачи: queries, lr, ss, comm, deep.
response.res_array object

Запрос → Да (геозависим) или Нет. Если топоним есть в самом запросе — всегда Нет: запрос уже локализован.
response.local_pow object

Запрос → доля ТОПа (в процентах), где в заголовке или сниппете встретился топоним региона.
response.data object

Только при intent: коммерциализация по каждому запросу.
Вложенные поля
- thematic_words array
  
  Тематические слова запроса.
- com int
  
  Процент коммерческих документов в ТОПе.
- rev int
  
  Процент документов с отзывами.
- media int
  
  Процент фото- и видеодокументов.
- lex int
  
  Процент словарных документов.
- music int
  
  Процент музыкальных документов.
- trav int
  
  Процент документов о путешествиях и отдыхе.
time string

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

Стоимость задачи в лимитах.

GET /api/geo

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

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

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

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

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

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

{
    "request": {
        "queries": [
            "мебель",
            "офисная мебель купить"
        ],
        "lr": "213",
        "ss": "yandex",
        "comm": "1",
        "deep": 50
    },
    "response": {
        "data": {
            "мебель": {
                "thematic_words": [
                    "диван",
                    "шкаф",
                    "кухня",
                    "каталог",
                    "цена"
                ],
                "com": 90,
                "rev": 6,
                "media": 8,
                "lex": 0,
                "music": 0,
                "trav": 0
            },
            "офисная мебель купить": {
                "thematic_words": [
                    "кресло",
                    "стол",
                    "офис",
                    "цена",
                    "доставка"
                ],
                "com": 98,
                "rev": 4,
                "media": 2,
                "lex": 0,
                "music": 0,
                "trav": 0
            }
        },
        "res_array": {
            "мебель": "Да",
            "офисная мебель купить": "Да"
        },
        "local_pow": {
            "мебель": 46,
            "офисная мебель купить": 70
        }
    },
    "time": "1759742512",
    "cost": 2
}

Ошибки

Код	Сообщение	Когда
`50`	`In progress`	Задача ещё выполняется. Это не сбой — повторите запрос с тем же `report_id` позже.
`-50`	`Requests empty or is not an array`	Не передан параметр `requests`.
`-51`	`No requests data`	Задача ставится не POST-запросом.
`-60`	`To many tasks from one user. Try again later.`	У пользователя уже больше 5 незавершённых задач этого инструмента.
`-68, -80…-83`	`Not enough … limits`	Не хватает лимитов: нужно 2 на каждый запрос. В ответе есть `available` и `need`.
`-4`	`Access denied`	`report_id` принадлежит другому пользователю или другому инструменту.
`-104`	`Processing error`	Задача завершилась с ошибкой.
`-105`	`Limits run out`	Лимиты закончились во время выполнения.
`-106`	`The process was canceled by a user`	Задача отменена пользователем.
`-107`	`The process took more than 6 hours and was canceled`	Задача выполнялась дольше 6 часов и снята автоматически.
`-125`	`Processing error`	Задача завершилась с непредвиденным статусом.
`-1, -2`	`Access denied`	Ключ не передан (HTTP 404) или не найден (HTTP 403).

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

{
    "error": "In progress",
    "code": 50
}

Как считается геозависимость

Запросы и тексты выдачи лемматизируются. Если в самом запросе есть название города, запрос считается уже локализованным: res_array = Нет, local_pow = 0. Иначе в каждом документе ТОПа ищется название региона из lr и его синонимы (СПб, Питер, Мск, Екб и т. п.). Каждый найденный документ добавляет 100 / deep процентов к local_pow; запрос геозависим, если найден хотя бы один такой документ.

Лимиты

Для постановки на балансе должно быть 2 лимита на запрос, а списывается 1 лимит на запрос — сразу при постановке, с коммерциализацией и без. Поле cost в результате показывает ту же сумму.

geo Проверка геозависимости запросов

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

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

Ответ

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

Параметры query

Ответ

Ошибки

Как считается геозависимость

Лимиты

`geo` Проверка геозависимости запросов