Maps Skill Guide: Geocoding, POIs, Routes, and Timezones

The Maps skill turns Hermes Agent into a location intelligence tool. It geocodes place names, reverse-geocodes coordinates, finds nearby points of interest, calculates travel distances and directions, and reports timezones, all from free, open data sources. You would reach for this when a user sends a location pin, asks for the nearest hospital, or wants walking directions between two landmarks, and you need an answer without an API key or extra dependencies.

What it does

This skill bundles eight commands that cover the common location tasks an assistant faces. It uses OpenStreetMap data through the Nominatim geocoder, the Overpass API for point-of-interest searches, OSRM for routing, and TimeAPI.io for timezone lookups. Everything runs on Python's standard library, so there is nothing to install. The skill replaces the older find-nearby skill; the nearby command now covers all of that functionality, including the --near "" shortcut and multi-category queries.

Before you start

You need Python 3.8 or newer. The script lives at ~/.hermes/skills/maps/scripts/maps_client.py. No pip installs are required, and no API key is needed. The skill works on Linux, macOS, and Windows.

Commands

Set a shell variable to keep the command lines short:

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

search, Geocode a place name

Turn a place name into coordinates and metadata:

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

Returns latitude, longitude, display name, type, bounding box, and an importance score. Use this when a user asks for the coordinates of a landmark or address.

reverse, Coordinates to address

Go the other direction, from coordinates to a full address:

python $MAPS reverse 48.8584 2.2945

Returns a breakdown with street, city, state, country, and postcode. This is handy when a user sends a pin and you want to confirm the address.

nearby, Find places by category

Search for points of interest around a location. You can give coordinates directly, or use --near with a place name, zip code, or landmark, and the script auto-geocodes it:

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

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

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

There are 46 categories: 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, a clickable maps_url link, a directions_url from the search point, and promoted tags when available: cuisine, hours (opening_hours), phone, and website.

distance, Travel distance and time

Get road distance and travel time between two places, with straight-line distance for comparison:

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

Modes are driving (default), walking, and cycling.

directions, Turn-by-turn navigation

Get step-by-step directions between two places:

python $MAPS directions "Eiffel Tower" --to "Louvre Museum" --mode walking
python $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.).

timezone, Timezone for coordinates

Find the timezone for a set of coordinates:

python $MAPS timezone 48.8584 2.2945
python $MAPS timezone 35.6762 139.6503

Returns timezone name, UTC offset, and current local time.

area, Bounding box and area for a place

Get the bounding box and approximate area for a named place:

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

Returns bounding box coordinates, width/height in km, and approximate area. This is useful as input for the bbox command.

bbox, Search within a bounding box

Search for points of interest inside a geographic rectangle:

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

Use area first to get the bounding box coordinates for a named place, then pass them here.

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"
python $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

Run these to confirm the skill works:

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

python ~/.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

When not to use it

If you need real-time traffic data, indoor mapping, or coverage outside the regions where OSRM is strong, this skill will fall short. For up-to-date opening hours, always cross-check with a web search because OSM data is community-maintained. For global zip code lookups, be ready to add country or state context to avoid ambiguity.

Limits and gotchas

The main constraints come from the free data sources. Nominatim's terms limit you to one request per second, which the script handles automatically, but you should not expect high-throughput geocoding. Overpass can be slow during peak hours, though the script falls back between mirrors. OSRM routing is best for Europe and North America, so routes elsewhere may be less reliable. Remember that distance and directions require the --to flag for the destination, not a positional argument.

Related skills

This skill pairs well with the web_search skill for verifying opening hours and with the Telegram integration for handling location pins. For broader productivity workflows, look at the other bundled skills in the Productivity category.