Samin12/skills

Compétence Cartes

Intelligence géographique utilisant des sources de données ouvertes et gratuites. 8 commandes, 44 catégories de POI, zéro dépendance (stdlib Python uniquement), aucune clé API requise.

Sources de données : OpenStreetMap/Nominatim, Overpass API, OSRM, TimeAPI.io.

Cette compétence remplace l'ancienne compétence find-nearby — toutes les fonctionnalités de find-nearby sont couvertes par la commande nearby ci-dessous, avec le même raccourci --near "<lieu>" et le support multi-catégorie.

Quand l'utiliser

• L'utilisateur envoie une épingle de localisation Telegram (latitude/longitude dans le message) → nearby
• L'utilisateur souhaite les coordonnées d'un nom de lieu → search
• L'utilisateur a des coordonnées et souhaite l'adresse → reverse
• L'utilisateur demande des restaurants, hôpitaux, pharmacies, hôtels, etc. à proximité → nearby
• L'utilisateur souhaite la distance ou le temps de trajet en voiture/à pied/à vélo → distance
• L'utilisateur souhaite un itinéraire détaillé entre deux lieux → directions
• L'utilisateur souhaite des informations de fuseau horaire pour un lieu → timezone
• L'utilisateur souhaite rechercher des POI dans une zone géographique → area + bbox

Prérequis

Python 3.8+ (stdlib uniquement — pas besoin de pip install).

Chemin du script : ~/.hermes/skills/maps/scripts/maps_client.py

Commandes

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

search — Géocode un nom de lieu

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

Retourne : lat, lon, nom d'affichage, type, cadre de délimitation, score d'importance.

reverse — Coordonnées vers adresse

python3 $MAPS reverse 48.8584 2.2945

Retourne : adresse complète décomposée (rue, ville, état, pays, code postal).

nearby — Trouve des lieux par catégorie

# Par coordonnées (depuis une épingle de localisation Telegram, par exemple)
python3 $MAPS nearby 48.8584 2.2945 restaurant --limit 10
python3 $MAPS nearby 40.7128 -74.0060 hospital --radius 2000

# Par adresse / ville / code postal / lieu emblématique — --near géocode automatiquement
python3 $MAPS nearby --near "Times Square, New York" --category cafe
python3 $MAPS nearby --near "75001" --category pharmacy

# Plusieurs catégories fusionnées en une seule requête
python3 $MAPS nearby --near "centre-ville lyon" --category restaurant --category bar --limit 10

46 catégories : 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.

Chaque résultat inclut : name, address, lat/lon, distance_m, maps_url (lien Google Maps cliquable), directions_url (itinéraire Google Maps depuis le point de recherche), et des balises mises en avant lorsqu'elles sont disponibles — cuisine, hours (heures d'ouverture), phone, website.

distance — Distance et temps de trajet

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

Modes : driving (par défaut), walking, cycling. Retourne la distance routière, la durée et la distance à vol d'oiseau pour comparaison.

directions — Itinéraire détaillé

python3 $MAPS directions "Tour Eiffel" --to "Musée du Louvre" --mode walking
python3 $MAPS directions "Aéroport JFK" --to "Times Square" --mode driving

Retourne des étapes numérotées avec indication, distance, durée, nom de route et type de manœuvre (tourner, partir, arriver, etc.).

timezone — Fuseau horaire pour des coordonnées

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

Retourne le nom du fuseau horaire, le décalage UTC et l'heure locale actuelle.

area — Cadre de délimitation et surface pour un lieu

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

Retourne les coordonnées du cadre de délimitation, la largeur/hauteur en km et la surface approximative. Utile comme entrée pour la commande bbox.

bbox — Recherche dans un cadre de délimitation

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

Trouve des POI dans un rectangle géographique. Utilisez area d'abord pour obtenir les coordonnées du cadre de délimitation d'un lieu nommé.

Travailler avec des épingles de localisation Telegram

Lorsqu'un utilisateur envoie une épingle de localisation, le message contient les champs latitude: et longitude:. Extrayez-les et passez-les directement à nearby :

# L'utilisateur a envoyé une épingle à 36.17, -115.14 et a demandé "trouve des cafés près d'ici"
python3 $MAPS nearby 36.17 -115.14 cafe --radius 1500

Présentez les résultats sous forme de liste numérotée avec les noms, distances et le champ maps_url pour que l'utilisateur obtienne un lien cliquable dans le chat. Pour les questions "ouvert maintenant ?", vérifiez le champ hours ; s'il est manquant ou peu clair, vérifiez avec web_search car les heures OSM sont gérées par la communauté et pas toujours à jour.

Exemples de workflows

"Trouve des restaurants italiens près du Colisée" :

1. nearby --near "Colisée Rome" --category restaurant --radius 500 — une seule commande, géocodée automatiquement

"Qu'y a-t-il près de cette épingle de localisation qu'ils ont envoyée ?" :

1. Extrayez lat/lon du message Telegram
2. nearby LAT LON cafe --radius 1500

"Comment aller à pied de l'hôtel au centre de conférence ?" :

1. directions "Nom de l'hôtel" --to "Centre de conférence" --mode walking

"Quels restaurants y a-t-il dans le centre-ville de Seattle ?" :

1. area "Centre-ville Seattle" → obtenez le cadre de délimitation
2. bbox S W N E restaurant --limit 30

Pièges

• Conditions d'utilisation de Nominatim : max 1 req/s (géré automatiquement par le script)
• nearby nécessite lat/lon OU --near "<adresse>" — l'un des deux est requis
• La couverture de routage OSRM est meilleure pour l'Europe et l'Amérique du Nord
• L'API Overpass peut être lente aux heures de pointe ; le script bascule automatiquement entre les miroirs (overpass-api.de → overpass.kumi.systems)
• distance et directions utilisent l'option --to pour la destination (pas positionnelle)
• Si un code postal seul donne des résultats ambigus à l'échelle mondiale, incluez le pays / l'état

Vérification

python3 ~/.hermes/skills/maps/scripts/maps_client.py search "Statue de la Liberté"
# Devrait retourner lat ~40.689, lon ~-74.044

python3 ~/.hermes/skills/maps/scripts/maps_client.py nearby --near "Times Square" --category restaurant --limit 3
# Devrait retourner une liste de restaurants dans un rayon d'environ 500 m de Times Square