Samin12/skills

Skill de Mapas

Inteligencia de ubicación utilizando fuentes de datos abiertas y gratuitas. 8 comandos, 44 categorías de POIs, cero dependencias (solo stdlib de Python), no se necesita clave API.

Fuentes de datos: OpenStreetMap/Nominatim, Overpass API, OSRM, TimeAPI.io.

Este skill reemplaza el antiguo skill find-nearby — toda la funcionalidad de find-nearby está cubierta por el comando nearby a continuación, con el mismo atajo --near "<lugar>" y soporte para múltiples categorías.

Cuándo Usarlo

• El usuario envía un pin de ubicación de Telegram (latitud/longitud en el mensaje) → nearby
• El usuario quiere coordenadas de un nombre de lugar → search
• El usuario tiene coordenadas y quiere la dirección → reverse
• El usuario pregunta por restaurantes, hospitales, farmacias, hoteles cercanos, etc. → nearby
• El usuario quiere distancia o tiempo de viaje conduciendo/caminando/andando en bici → distance
• El usuario quiere indicaciones paso a paso entre dos lugares → directions
• El usuario quiere información de huso horario para una ubicación → timezone
• El usuario quiere buscar POIs dentro de un área geográfica → area + bbox

Prerrequisitos

Python 3.8+ (solo stdlib — no se necesitan instalaciones con pip).

Ruta del script: ~/.hermes/skills/maps/scripts/maps_client.py

Comandos

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

search — Geocodificar un nombre de lugar

python3 $MAPS search "Torre Eiffel"
python3 $MAPS search "1600 Pennsylvania Ave, Washington DC"

Devuelve: lat, lon, nombre mostrado, tipo, cuadro delimitador, puntuación de importancia.

reverse — Coordenadas a dirección

python3 $MAPS reverse 48.8584 2.2945

Devuelve: desglose completo de la dirección (calle, ciudad, estado, país, código postal).

nearby — Encontrar lugares por categoría

# Por coordenadas (por ejemplo, desde un pin de ubicación de Telegram)
python3 $MAPS nearby 48.8584 2.2945 restaurant --limit 10
python3 $MAPS nearby 40.7128 -74.0060 hospital --radius 2000

# Por dirección / ciudad / código postal / punto de referencia — --near geocodifica automáticamente
python3 $MAPS nearby --near "Times Square, Nueva York" --category cafe
python3 $MAPS nearby --near "90210" --category pharmacy

# Múltiples categorías combinadas en una sola consulta
python3 $MAPS nearby --near "centro de austin" --category restaurant --category bar --limit 10

46 categorías: 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.

Cada resultado incluye: name, address, lat/lon, distance_m, maps_url (enlace clickable a Google Maps), directions_url (indicaciones de Google Maps desde el punto de búsqueda), y etiquetas promocionadas cuando están disponibles — cuisine, hours (opening_hours), phone, website.

distance — Distancia y tiempo de viaje

python3 $MAPS distance "París" --to "Lyon"
python3 $MAPS distance "Nueva York" --to "Boston" --mode driving
python3 $MAPS distance "Big Ben" --to "Tower Bridge" --mode walking

Modos: driving (por defecto), walking, cycling. Devuelve distancia por carretera, duración y distancia en línea recta para comparación.

directions — Navegación paso a paso

python3 $MAPS directions "Torre Eiffel" --to "Museo del Louvre" --mode walking
python3 $MAPS directions "Aeropuerto JFK" --to "Times Square" --mode driving

Devuelve pasos numerados con instrucción, distancia, duración, nombre de la calle y tipo de maniobra (turn, depart, arrive, etc.).

timezone — Huso horario para coordenadas

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

Devuelve nombre del huso horario, desplazamiento UTC y hora local actual.

area — Cuadro delimitador y área para un lugar

python3 $MAPS area "Manhattan, Nueva York"
python3 $MAPS area "Londres"

Devuelve coordenadas del cuadro delimitador, ancho/alto en km y área aproximada. Útil como entrada para el comando bbox.

bbox — Buscar dentro de un cuadro delimitador

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

Encuentra POIs dentro de un rectángulo geográfico. Usa area primero para obtener las coordenadas del cuadro delimitador de un lugar nombrado.

Trabajar con pines de ubicación de Telegram

Cuando un usuario envía un pin de ubicación, el mensaje contiene los campos latitude: y longitude:. Extrae esos y pásalos directamente a nearby:

# El usuario envió un pin en 36.17, -115.14 y preguntó "encuentra cafeterías cercanas"
python3 $MAPS nearby 36.17 -115.14 cafe --radius 1500

Presenta los resultados como una lista numerada con nombres, distancias y el campo maps_url para que el usuario tenga un enlace de "tocar para abrir" en el chat. Para preguntas de "¿abierto ahora?", verifica el campo hours; si falta o no está claro, verifica con web_search ya que los horarios de OSM son mantenidos por la comunidad y no siempre están actualizados.

Ejemplos de Flujo de Trabajo

"Encuentra restaurantes italianos cerca del Coliseo":

1. nearby --near "Coliseo Roma" --category restaurant --radius 500 — un solo comando, geocodificado automáticamente

"¿Qué hay cerca del pin de ubicación que enviaron?":

1. Extrae lat/lon del mensaje de Telegram
2. nearby LAT LON cafe --radius 1500

"¿Cómo camino del hotel al centro de conferencias?":

1. directions "Nombre del hotel" --to "Centro de Conferencias" --mode walking

"¿Qué restaurantes hay en el centro de Seattle?":

1. area "Centro de Seattle" → obtén el cuadro delimitador
2. bbox S W N E restaurant --limit 30

Problemas Comunes

• ToS de Nominatim: máximo 1 req/s (manejado automáticamente por el script)
• nearby requiere lat/lon O --near "<dirección>" — se necesita uno de los dos
• La cobertura de enrutamiento de OSRM es mejor para Europa y América del Norte
• Overpass API puede ser lento durante horas pico; el script cambia automáticamente entre servidores espejo (overpass-api.de → overpass.kumi.systems)
• distance y directions usan el indicador --to para el destino (no posicional)
• Si un código postal solo da resultados ambiguos globalmente, incluye país/estado

Verificación

python3 ~/.hermes/skills/maps/scripts/maps_client.py search "Estatua de la Libertad"
# Debería devolver lat ~40.689, lon ~-74.044

python3 ~/.hermes/skills/maps/scripts/maps_client.py nearby --near "Times Square" --category restaurant --limit 3
# Debería devolver una lista de restaurantes a ~500m de Times Square