| name | yandex-position-checker |
| version | 1.0.0 |
| description | Yandex Maps position checker via public endpoint. Use when checking card positions on Yandex Maps, local SERP visibility, geo-dependent ranking, or reproducing free checker logic from loocl.ru/tools/position-checker. |
| license | MIT |
| metadata | {"author":"esporykhin","version":"1.0.0"} |
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 или targetOrgUrlcoordinates.lat, coordinates.lonradiusKm
Координаты можно передавать тремя способами:
- явно (
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) отправляет:
queriestargetOrgId или targetOrgUrlcoordinatesradiusKm
Скрипт check-position-free.sh поддерживает совместимый формат (radius в метрах) и маппит в контракт endpoint.
Подробнее: references/free-checker-mapping.md
Scripts
Готовые shell-скрипты в scripts/.
| Script | Purpose | Usage |
|---|
check-position.sh | Универсальная проверка позиции (URL/ID + запросы) | ./scripts/check-position.sh "https://yandex.ru/maps/org/..." "барбершоп,мужская стрижка" 55.75 37.61 2 |
check-position-free.sh | Совместимый с free-checker формат (organization + keywords + radius в метрах) | ./scripts/check-position-free.sh "https://yandex.ru/maps/org/..." "барбершоп,мужская стрижка" "Москва, Тверская 7" 2000 |
check-position-raw.sh | Отправка сырого JSON в check-positions | ./scripts/check-position-raw.sh '{"queries":["барбершоп"],"targetOrgId":"123"}' |
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-геокодирование, но должен явно предупредить пользователя, что для точности по РФ лучше ключ Яндекс Геокодера.
