Перейти к основному содержимому

Карты

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

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

ИсточникВстроенный (установлен по умолчанию)
Путьskills/productivity/maps
Версия1.2.0
АвторMibayy
ЛицензияMIT
Платформыlinux, macos, windows
Тегиmaps, geocoding, places, routing, distance, directions, nearby, location, openstreetmap, nominatim, overpass, osrm

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

к сведению

Ниже приведено полное описание навыка, которое VibeOS загружает при его активации. Это те инструкции, которые видит агент, когда навык активен.

Навык «Карты»

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

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

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

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

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

Предварительные требования​

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

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

Команды​

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

search — Геокодирование названия места​

python3 $MAPS search "Эйфелева башня"
python3 $MAPS search "1600 Pennsylvania Ave, Washington DC"

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

reverse — Координаты в адрес​

python3 $MAPS reverse 48.8584 2.2945

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

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

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

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

# Несколько категорий, объединённых в один запрос
python3 $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 Карты), directions_url (маршрут Google Карт от точки поиска), а также продвигаемые теги при наличии — cuisine, hours (часы работы), phone, website.

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

python3 $MAPS distance "Париж" --to "Лион"
python3 $MAPS distance "Нью-Йорк" --to "Бостон" --mode driving
python3 $MAPS distance "Биг-Бен" --to "Тауэрский мост" --mode walking

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

directions — Пошаговая навигация​

python3 $MAPS directions "Эйфелева башня" --to "Лувр" --mode walking
python3 $MAPS directions "Аэропорт JFK" --to "Таймс-сквер" --mode driving

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

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

python3 $MAPS timezone 48.8584 2.2945
python3 $MAPS timezone 35.6762 139.6503

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

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

python3 $MAPS area "Манхэттен, Нью-Йорк"
python3 $MAPS area "Лондон"

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

bbox — Поиск в пределах ограничивающего прямоугольника​

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

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

Работа с геометками Telegram​

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

# Пользователь отправил метку в 36.17, -115.14 и спросил «найди кафе рядом»
python3 $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. Извлеките широту/долготу из сообщения Telegram
  2. nearby LAT LON cafe --radius 1500

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

  1. directions "Название отеля" --to "Конференц-центр" --mode walking

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

  1. area "Downtown Seattle" → получить ограничивающий прямоугольник
  2. bbox S W N E restaurant --limit 30

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

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

Проверка​

python3 ~/.vibeos/skills/maps/scripts/maps_client.py search "Статуя Свободы"
# Должен вернуть широту ~40.689, долготу ~-74.044

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