Skill de Mapas
Inteligencia de ubicación utilizando fuentes de datos abiertas y gratuitas. 8 comandos, 44 categorías de POI, cero dependencias (solo stdlib de Python), sin necesidad de clave API.
Fuentes de datos: OpenStreetMap/Nominatim, Overpass API, OSRM, TimeAPI.io.
Esta skill reemplaza la antigua 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 Usar
- El usuario envía un pin de ubicación de Telegram (latitud/longitud en el mensaje) →
nearby - El usuario quiere coordenadas para un nombre de lugar →
search - El usuario tiene coordenadas y quiere la dirección →
reverse - El usuario pregunta por restaurantes, hospitales, farmacias, hoteles, etc. cercanos →
nearby - El usuario quiere la distancia o tiempo de viaje en coche, a pie o en bicicleta →
distance - El usuario quiere indicaciones paso a paso entre dos lugares →
directions - El usuario quiere información de zona horaria 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 auto-geocodifica
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 de 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 (predeterminado), walking, cycling. Devuelve la distancia por carretera, la duración y la distancia en línea recta para comparar.
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 carretera y tipo de maniobra (turn, depart, arrive, etc.).
timezone — Zona horaria para coordenadas
python3 $MAPS timezone 48.8584 2.2945
python3 $MAPS timezone 35.6762 139.6503
Devuelve el nombre de la zona horaria, el desplazamiento UTC y la hora local actual.
area — Cuadro delimitador y área de 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. Use area primero para obtener las coordenadas del cuadro delimitador de un lugar nombrado.
Cómo 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:. Extráigalo y páselo 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
Presente los resultados como una lista numerada con nombres, distancias y el campo
maps_url para que el usuario tenga un enlace con un solo toque en el chat. Para preguntas
como "¿está abierto ahora?", verifique el campo hours; si falta o no está claro,
verifique 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":
nearby --near "Coliseo Roma" --category restaurant --radius 500— un solo comando, auto-geocodificado
"¿Qué hay cerca de este pin de ubicación que enviaron?":
- Extraiga lat/lon del mensaje de Telegram
nearby LAT LON cafe --radius 1500
"¿Cómo camino desde el hotel hasta el centro de convenciones?":
directions "Nombre del Hotel" --to "Centro de Convenciones" --mode walking
"¿Qué restaurantes hay en el centro de Seattle?":
area "Centro de Seattle"→ obtenga el cuadro delimitadorbbox S W N E restaurant --limit 30
Problemas Comunes
- ToS de Nominatim: máximo 1 req/s (manejado automáticamente por el script)
nearbyrequiere 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 lenta durante horas pico; el script cambia automáticamente entre espejos (overpass-api.de → overpass.kumi.systems)
distanceydirectionsusan la bandera--topara el destino (no posicional)- Si un código postal solo da resultados ambiguos a nivel mundial, incluya el 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 ~500 m de Times Square