Yandex Position Checker

Yandex Position Checker

Скилл для проверки позиций карточки организации в Яндекс Картах через endpoint POST /api/tools/check-positions.

Основной endpoint: POST /api/tools/check-positions.

When to Apply

• Нужно проверить позицию карточки в Яндекс Картах по ключевым запросам
• Нужно повторить логику бесплатного чекера с https://loocl.ru/tools/position-checker
• Нужно быстро сделать разовую/пакетную проверку локальной выдачи
• Нужно сравнить позиции при разных координатах/радиусах

Base URL

По умолчанию скрипты используют:

https://loocl.ru

Переопредели через env:

YANDEX_POSITION_CHECKER_BASE_URL=https://your-domain

Также значение может быть задано в config/.env внутри скилла (см. config/README.md). Для обратной совместимости поддерживается и LOOCL_BASE_URL.

Если config/.env нет и хочешь что-то переопределить — агент может спросить значения у пользователя и предложить два варианта: кинуть в чат (агент создаст config/.env сам) или скопировать config/.env.example вручную.

Endpoint Summary

POST /api/tools/check-positions

Ключевые поля запроса:

• queries[] (в UI free checker используется до 5)
• targetOrgId или targetOrgUrl
• coordinates.lat, coordinates.lon
• radiusKm

Координаты можно передавать тремя способами:

• явно (lat, lon)
• строкой адреса (геокодирование в координаты)
• строкой lat,lon

Логика target как в free checker:

• если строка состоит только из цифр -> targetOrgId
• если это URL карточки .../org/.../<id> -> targetOrgId
• иначе, если это URL -> targetOrgUrl
• иначе -> targetOrgId

Подробнее: references/endpoint-check-positions.md

Free Checker Mapping

Бесплатный чекер (/tools/position-checker) отправляет:

• queries
• targetOrgId или targetOrgUrl
• coordinates
• radiusKm

Скрипт check-position-free.sh поддерживает совместимый формат (radius в метрах) и маппит в контракт endpoint.

Подробнее: references/free-checker-mapping.md

Scripts

Готовые shell-скрипты в scripts/.

Which Script to Use

• У тебя есть URL/ID карточки + список запросов -> check-position.sh
• Нужно повторить формат бесплатного чекера (радиус в метрах) -> check-position-free.sh
• Нужен полный контроль над JSON запроса -> check-position-raw.sh

Location Resolution Notes

• check-position.sh:
• старый формат: <lat> <lon> [radius_km]
• новый формат: <location|lat,lon> [radius_km]
• check-position-free.sh:
• старый формат: <lat> <lon> [radius_meters] [organization_name]
• новый формат: <location|lat,lon|address> [radius_meters] [organization_name]
• Если задан YANDEX_GEOCODER_API_KEY, адреса сначала пробуются через Yandex Geocoder, иначе используется Nominatim (OpenStreetMap).

Agent Instruction for Address Checks

• Если пользователь хочет проверять позиции по конкретным адресам, агент должен попросить YANDEX_GEOCODER_API_KEY и использовать его в вызовах.
• Предпочтительный сценарий для адресов: YANDEX_GEOCODER_API_KEY установлен + адрес передается строкой в check-position.sh / check-position-free.sh.
• Если ключ не предоставлен, агент может использовать fallback-геокодирование, но должен явно предупредить пользователя, что для точности по РФ лучше ключ Яндекс Геокодера.