> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mibyanai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Maps — Geocode, POIs, routes, timezones via OpenStreetMap/OSRM

> Geocode, POIs, routes, timezones via OpenStreetMap/OSRM

Geocode, POIs, routes, timezones via OpenStreetMap/OSRM.

## Skill metadata

| | |
| - | - |
| Source | Bundled (installed by default) |
| Path | `skills/productivity/maps` |
| Version | `1.2.0` |
| Author | Mibayy |
| License | MIT |
| Platforms | linux, macos, windows |
| Tags | `maps`, `geocoding`, `places`, `routing`, `distance`, `directions`, `nearby`, `location`, `openstreetmap`, `nominatim`, `overpass`, `osrm` |

## Reference: full SKILL.md

<Info>
  The following is the complete skill definition that Mibyan loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
</Info>

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

This skill supersedes the old `find-nearby` skill — all of find-nearby's
functionality is covered by the `nearby` command below, with the same
`--near "<place>"` shortcut and multi-category support.

## When to Use

* User sends a Telegram location pin (latitude/longitude in the message) → `nearby`
* User wants coordinates for a place name → `search`
* User has coordinates and wants the address → `reverse`
* User asks for nearby restaurants, hospitals, pharmacies, hotels, etc. → `nearby`
* User wants driving/walking/cycling distance or travel time → `distance`
* User wants turn-by-turn directions between two places → `directions`
* User wants timezone information for a location → `timezone`
* User wants to search for POIs within a geographic area → `area` + `bbox`

## Prerequisites

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

Script path: `~/.mibyan/skills/maps/scripts/maps_client.py`

## Commands

```bash theme={null}
MAPS=~/.mibyan/skills/maps/scripts/maps_client.py
```

### search — Geocode a place name

```bash theme={null}
python $MAPS search "Eiffel Tower"
python $MAPS search "1600 Pennsylvania Ave, Washington DC"
```

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

### reverse — Coordinates to address

```bash theme={null}
python $MAPS reverse 48.8584 2.2945
```

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

### nearby — Find places by category

```bash theme={null}
# 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
```

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`,
`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

```bash theme={null}
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: driving (default), walking, cycling. Returns road distance, duration,
and straight-line distance for comparison.

### directions — Turn-by-turn navigation

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
python $MAPS area "Manhattan, New York"
python $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

```bash theme={null}
python $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.

## 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`:

```bash theme={null}
# 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 "<address>"` — 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

```bash theme={null}
python ~/.mibyan/skills/maps/scripts/maps_client.py search "Statue of Liberty"
# Should return lat ~40.689, lon ~-74.044

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.