Maps Skill for Hermes Agent: Geocoding, POIs, Routes & Timezones via OSM

The Maps skill turns Hermes Agent into a location-aware assistant without requiring a single API key. It geocodes place names, finds nearby points of interest, calculates driving/walking/cycling routes, and looks up timezones, all from free, open data sources (OpenStreetMap, Nominatim, Overpass API, OSRM, TimeAPI.io). If your agent receives a Telegram location pin or a user asks "what's near the hotel?", this is the skill you reach for.

What it does

Eight commands cover the most common location tasks a conversational agent needs:

• search, Turn a place name into coordinates and metadata.
• reverse, Turn coordinates into a full address.
• nearby, Find places by category (restaurants, hospitals, gas stations, etc.) within a radius.
• distance, Get road distance and travel time between two places.
• directions, Get turn-by-turn walking, driving, or cycling instructions.
• timezone, Get timezone name, UTC offset, and current local time for a coordinate.
• area, Get the bounding box and approximate area for a named place.
• bbox, Search for POIs inside a geographic rectangle.

This skill replaces the old find-nearby skill. Everything find-nearby did is now covered by the nearby command, including the --near "" shortcut and multi-category support.

Before you start

• Python 3.8+ is required. No pip installs are needed; the script uses only the Python standard library.
• The script lives at ~/.hermes/skills/maps/scripts/maps_client.py. You can alias it for convenience:

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

• No API keys, no registration, no rate-limiting accounts. The script respects Nominatim's 1 request per second limit automatically.

Commands

search, Geocode a place name

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

Returns latitude, longitude, display name, place type, bounding box, and an importance score. Use this when a user says "find the coordinates of..." or when you need to feed coordinates into another command.

reverse, Coordinates to address

python3 $MAPS reverse 48.8584 2.2945

Returns a full address breakdown: street, city, state, country, postcode. Use this when a user sends a location pin and asks "what's this place?"

nearby, Find places by category

# By coordinates (from a Telegram location pin, for example)
python3 $MAPS nearby 48.8584 2.2945 restaurant --limit 10
python3 $MAPS nearby 40.7128 -74.0060 hospital --radius 2000

# By address / city / zip / landmark — --near auto-geocodes
python3 $MAPS nearby --near "Times Square, New York" --category cafe
python3 $MAPS nearby --near "90210" --category pharmacy

# Multiple categories merged into one query
python3 $MAPS nearby --near "downtown austin" --category restaurant --category bar --limit 10

46 categories are available: 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.

Each result includes: name, address, lat/lon, distance_m, maps_url (clickable Google Maps link), directions_url (Google Maps directions from the search point), and promoted tags when available, cuisine, hours (opening_hours), phone, website.

distance, Travel distance and time

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 (default), walking, cycling. Returns road distance, duration, and straight-line distance for comparison. Use this when a user asks "how far is it from X to Y?" or "how long would it take to drive?"

directions, Turn-by-turn navigation

python3 $MAPS directions "Eiffel Tower" --to "Louvre Museum" --mode walking
python3 $MAPS directions "JFK Airport" --to "Times Square" --mode driving

Returns numbered steps with instruction, distance, duration, road name, and maneuver type (turn, depart, arrive, etc.). Use this when a user wants actual walking or driving directions, not just distance.

timezone, Timezone for coordinates

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

Returns timezone name, UTC offset, and current local time. Use this when a user asks "what time is it in Tokyo?" or "what's the timezone of this location?"

area, Bounding box and area for a place

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

Returns bounding box coordinates, width/height in km, and approximate area. This is a helper command: its output is designed to be fed into the bbox command.

bbox, Search within a bounding box

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

Finds POIs within a geographic rectangle. Use area first to get the bounding box coordinates for a named place, then pass them here. This is useful for "what's in this neighborhood?" queries where a simple radius search isn't precise enough.

Working With Telegram Location Pins

When a user sends a location pin, the message contains latitude: and longitude: fields. Extract those and pass them straight to nearby:

# User sent a pin at 36.17, -115.14 and asked "find cafes nearby"
python3 $MAPS nearby 36.17 -115.14 cafe --radius 1500

Present results as a numbered list with names, distances, and the maps_url field so the user gets a tap-to-open link in chat. For "open now?" questions, check the hours field; if missing or unclear, verify with web_search since OSM hours are community-maintained and not always current.

Workflow Examples

"Find Italian restaurants near the Colosseum":

1. nearby --near "Colosseum Rome" --category restaurant --radius 500, one command, auto-geocoded

"What's near this location pin they sent?":

1. Extract lat/lon from the Telegram message
2. nearby LAT LON cafe --radius 1500

"How do I walk from hotel to conference center?":

1. directions "Hotel Name" --to "Conference Center" --mode walking

"What restaurants are in downtown Seattle?":

1. area "Downtown Seattle" → get bounding box
2. bbox S W N E restaurant --limit 30

Pitfalls

• Nominatim ToS: max 1 req/s (handled automatically by the script)
• nearby requires lat/lon OR --near "", one of the two is needed
• OSRM routing coverage is best for Europe and North America
• Overpass API can be slow during peak hours; the script automatically falls back between mirrors (overpass-api.de → overpass.kumi.systems)
• distance and directions use --to flag for the destination (not positional)
• If a zip code alone gives ambiguous results globally, include country/state

Verification

python3 ~/.hermes/skills/maps/scripts/maps_client.py search "Statue of Liberty"
# Should return lat ~40.689, lon ~-74.044

python3 ~/.hermes/skills/maps/scripts/maps_client.py nearby --near "Times Square" --category restaurant --limit 3
# Should return a list of restaurants within ~500m of Times Square