Compétence Cartes

Que fait Compétence Cartes ?

Intelligence de localisation 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 la prise en charge multi-catégories.

Quand 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 à proximité, etc. → nearby
• L'utilisateur souhaite la distance ou le temps de trajet en voiture/marche/vélo → distance
• L'utilisateur souhaite un itinéraire détaillé entre deux endroits → directions
• L'utilisateur souhaite des informations de fuseau horaire pour un emplacement → timezone
• L'utilisateur souhaite rechercher des POI dans une zone géographique → area + bbox

Prérequis

Python 3.8+ (stdlib uniquement — aucune installation pip nécessaire).

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

Commandes

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

search — Géocoder 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 : ventilation complète de l'adresse (rue, ville, état, pays, code postal).

nearby — Trouver des lieux par catégorie

# Par coordonnées (à partir d'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 / point de repère — --near auto-géocode
python3 $MAPS nearby --near "Times Square, New York" --category cafe
python3 $MAPS nearby --near "90210" --category pharmacy

# Plusieurs catégories fusionnées en une seule requête
python3 $MAPS nearby --near "downtown austin" --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 cliquable Google Maps), directions_url (itinéraire Google Maps depuis le point de recherche), et des balises promues lorsqu'elles sont disponibles — cuisine, hours (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 — Navigation étape par étape

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 instruction, distance, durée, nom de rue, et type de manœuvre (turn, depart, arrive, 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 zone pour un lieu

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

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

bbox — Rechercher 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 pour un lieu nommé.

Travailler avec les é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 à proximité"
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 afin que l'utilisateur dispose d'un lien cliquable dans le chat. Pour les questions du type "ouvert maintenant ?", vérifiez le champ hours ; s'il manque ou n'est pas clair, vérifiez avec web_search car les horaires OSM sont maintenus par la communauté et ne sont pas toujours à jour.

Exemples de flux de travail

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

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

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

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

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

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

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

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

Pièges

• CGU de Nominatim : max 1 req/s (géré automatiquement par le script)
• nearby nécessite une lat/lon OU --near "<adresse>" — l'un des deux est nécessaire
• 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 le drapeau --to pour la destination (pas positionnel)
• 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é"
# Doit retourner lat ~40.689, lon ~-74.044

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