Maps

Геокодирование, POI, маршруты, часовые пояса через OpenStreetMap/OSRM.

Метаданные навыка

Справочник: полный SKILL.md

Maps Skill

Геолокационные возможности на бесплатных открытых данных. 8 команд, 44 категории POI, никаких зависимостей (только стандартная библиотека Python), API-ключ не нужен.

Источники данных: OpenStreetMap/Nominatim, Overpass API, OSRM, TimeAPI.io.

Этот навык заменяет устаревший find-nearby — вся его функциональность покрыта командой nearby ниже, включая ярлык --near "<place>" и поддержку нескольких категорий одновременно.

Когда использовать

• Пользователь прислал геопин Telegram (широта/долгота в сообщении) → nearby
• Нужны координаты по названию места → search
• Есть координаты, нужен адрес → reverse
• Пользователь спрашивает ближайшие рестораны, больницы, аптеки, отели и т. д. → nearby
• Нужна дистанция или время в пути (авто/пешком/велосипед) → distance
• Нужен маршрут с пошаговыми указаниями между двумя точками → directions
• Нужен часовой пояс для координат → timezone
• Поиск POI внутри географической области → area + bbox

Требования

Python 3.8+ (только стандартная библиотека — pip-установки не требуются).

Путь к скрипту: ~/.hermes/skills/maps/scripts/maps_client.py

Команды

MAPS=~/.hermes/skills/maps/scripts/maps_client.py

search — Геокодирование по названию

python $MAPS search "Eiffel Tower"
python $MAPS search "1600 Pennsylvania Ave, Washington DC"

Возвращает: широту, долготу, отображаемое название, тип, ограничивающий прямоугольник (bounding box), оценку релевантности.

reverse — Адрес по координатам

python $MAPS reverse 48.8584 2.2945

Возвращает: полную разбивку адреса (улица, город, регион, страна, почтовый индекс).

nearby — Поиск мест по категории

# По координатам (например, из геопина Telegram)
python $MAPS nearby 48.8584 2.2945 restaurant --limit 10
python $MAPS nearby 40.7128 -74.0060 hospital --radius 2000

# По адресу / городу / индексу / ориентиру — --near геокодирует автоматически
python $MAPS nearby --near "Times Square, New York" --category cafe
python $MAPS nearby --near "90210" --category pharmacy

# Несколько категорий объединяются в один запрос
python $MAPS nearby --near "downtown austin" --category restaurant --category bar --limit 10

46 категорий: restaurant, cafe, bar, hospital, pharmacy, hotel, guest_house, camp_site, supermarket, atm, gas_station, parking, museum, park, school, university, bank, police, fire_station, library, airport, train_station, bus_stop, church, mosque, synagogue, dentist, doctor, cinema, theatre, gym, swimming_pool, post_office, convenience_store, bakery, bookshop, laundry, car_wash, car_rental, bicycle_rental, taxi, veterinary, zoo, playground, stadium, nightclub.

Каждый результат содержит: name, address, lat/lon, distance_m, maps_url (кликабельная ссылка на Google Maps), directions_url (маршрут в Google Maps от точки поиска), а также дополнительные теги при наличии — cuisine, hours (opening_hours), phone, website.

distance — Расстояние и время в пути

python $MAPS distance "Paris" --to "Lyon"
python $MAPS distance "New York" --to "Boston" --mode driving
python $MAPS distance "Big Ben" --to "Tower Bridge" --mode walking

Режимы: driving (по умолчанию), walking, cycling. Возвращает расстояние по дороге, время в пути и расстояние по прямой для сравнения.

directions — Пошаговый маршрут

python $MAPS directions "Eiffel Tower" --to "Louvre Museum" --mode walking
python $MAPS directions "JFK Airport" --to "Times Square" --mode driving

Возвращает пронумерованные шаги с инструкцией, расстоянием, временем, названием дороги и типом манёвра (поворот, начало, прибытие и т. д.).

timezone — Часовой пояс по координатам

python $MAPS timezone 48.8584 2.2945
python $MAPS timezone 35.6762 139.6503

Возвращает название часового пояса, смещение UTC и текущее местное время.

area — Ограничивающий прямоугольник и площадь места

python $MAPS area "Manhattan, New York"
python $MAPS area "London"

Возвращает координаты bounding box, ширину и высоту в км, приблизительную площадь. Удобно как входные данные для команды bbox.

bbox — Поиск внутри bounding box

python $MAPS bbox 40.75 -74.00 40.77 -73.98 restaurant --limit 20

Находит POI внутри географического прямоугольника. Сначала запустите area, чтобы получить координаты bounding box для нужного места.

Работа с геопинами Telegram

Когда пользователь присылает геопин, сообщение содержит поля latitude: и longitude:. Извлеките их и передайте напрямую в nearby:

# Пользователь отправил пин с координатами 36.17, -115.14 и спросил "найди кафе поблизости"
python $MAPS nearby 36.17 -115.14 cafe --radius 1500

Выводите результаты нумерованным списком с названиями, расстояниями и полем maps_url — так пользователь получит ссылку прямо в чате. Для вопросов “открыто ли сейчас?” проверяйте поле hours; если его нет или данные неоднозначны — уточните через web_search, поскольку часы работы в OSM поддерживаются сообществом и не всегда актуальны.

Примеры сценариев

“Найди итальянские рестораны рядом с Колизеем”:

1. nearby --near "Colosseum Rome" --category restaurant --radius 500 — одна команда, геокодирование автоматически

“Что есть рядом с этим геопином?”:

1. Извлеките lat/lon из сообщения Telegram
2. nearby LAT LON cafe --radius 1500

“Как дойти от отеля до конференц-центра пешком?”:

1. directions "Hotel Name" --to "Conference Center" --mode walking

“Какие рестораны есть в центре Сиэтла?”:

1. area "Downtown Seattle" → получить bounding box
2. bbox S W N E restaurant --limit 30

Подводные камни

• Nominatim ToS: не более 1 запроса в секунду (скрипт обрабатывает это автоматически)
• nearby требует либо lat/lon, либо --near "<address>" — одно из двух обязательно
• Покрытие маршрутизации OSRM лучше всего для Европы и Северной Америки
• Overpass API может работать медленно в часы пик; скрипт автоматически переключается между зеркалами (overpass-api.de → overpass.kumi.systems)
• В командах distance и directions пункт назначения передаётся через флаг --to (не позиционным аргументом)
• Если почтовый индекс без указания страны/штата даёт неоднозначные результаты, добавьте уточнение

Проверка

python ~/.hermes/skills/maps/scripts/maps_client.py search "Statue of Liberty"
# Должно вернуть lat ~40.689, lon ~-74.044

python ~/.hermes/skills/maps/scripts/maps_client.py nearby --near "Times Square" --category restaurant --limit 3
# Должно вернуть список ресторанов в радиусе ~500 м от Times Square