mirrors/hermes-agent
1
0
Fork 0
mirror of https://github.com/NousResearch/hermes-agent.git synced 2026-04-25 00:51:20 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
hermes-agent/optional-skills/productivity/maps/SKILL.md
Mibayy 7fa01fafa5 feat: add maps skill (OpenStreetMap + Overpass + OSRM, no API key) 
Adds a maps optional skill with 8 commands, 44 POI categories, and
zero external dependencies. Uses free open data: Nominatim, Overpass
API, OSRM, and TimeAPI.io.

Commands: search, reverse, nearby, distance, directions, timezone,
area, bbox.

Improvements over original PR #2015:
- Fixed directory structure (optional-skills/productivity/maps/)
- Fixed distance argparse (--to flag instead of broken dual nargs=+)
- Fixed timezone (TimeAPI.io instead of broken worldtimeapi heuristic)
- Expanded POI categories from 12 to 44
- Added directions command with turn-by-turn OSRM steps
- Added area command (bounding box + dimensions for a named place)
- Added bbox command (POI search within a geographic rectangle)
- Added 23 unit tests
- Improved haversine (atan2 for numerical stability)
- Comprehensive SKILL.md with workflow examples

Co-authored-by: Mibayy <Mibayy@users.noreply.github.com>
2026-04-19 05:19:22 -07:00

4.6 KiB
Raw Blame History

name description version author license metadata
maps Geocoding, reverse geocoding, nearby POI search (44 categories), distance/routing, turn-by-turn directions, timezone lookup, bounding box search, and area info. Uses OpenStreetMap + Overpass + OSRM. Free, no API key. 1.1.0 Mibayy MIT
hermes
tags category requires_toolsets
maps
geocoding
places
routing
distance
directions
openstreetmap
nominatim
overpass
osrm
productivity
terminal

Maps Skill

Location intelligence using free, open data sources. 8 commands, 44 POI categories, zero dependencies (Python stdlib only), no API key required.

Data sources: OpenStreetMap/Nominatim, Overpass API, OSRM, TimeAPI.io.

When to Use

  • User wants coordinates for a place name
  • User has coordinates and wants the address
  • User asks for nearby restaurants, hospitals, pharmacies, hotels, etc.
  • User wants driving/walking/cycling distance or travel time
  • User wants turn-by-turn directions between two places
  • User wants timezone information for a location
  • User wants to search for POIs within a geographic area

Prerequisites

Python 3.8+ (stdlib only — no pip installs needed).

Script path after install: ~/.hermes/skills/maps/scripts/maps_client.py

Commands

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

search — Geocode a place name

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

Returns: lat, lon, display name, type, bounding box, importance score.

reverse — Coordinates to address

python3 $MAPS reverse 48.8584 2.2945

Returns: full address breakdown (street, city, state, country, postcode).

nearby — Find places by category

python3 $MAPS nearby 48.8584 2.2945 restaurant --limit 10
python3 $MAPS nearby 40.7128 -74.0060 hospital --radius 2000
python3 $MAPS nearby 51.5074 -0.1278 cafe --limit 5 --radius 300

44 categories: restaurant, cafe, bar, hospital, pharmacy, hotel, 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.

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.

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.).

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.

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. Useful as input for 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.

Workflow Examples

"Find Italian restaurants near the Colosseum":

  1. search "Colosseum Rome" → get lat/lon
  2. nearby LAT LON restaurant --radius 500

"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 — use search first to get coordinates
  • OSRM routing coverage is best for Europe and North America
  • Overpass API can be slow during peak hours (script retries automatically)
  • distance and directions use --to flag for the destination (not positional)

Verification

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