# Yoro Maps

**[Documentation](https://altius-academy-snc.github.io/yoro-maps/)** | **[PyPI](https://pypi.org/project/yoro-maps/)** | **[GitHub](https://github.com/Altius-Academy-SNC/yoro-maps)**

---

**Offline maps, routing, and POI for Africa** — companion to [yoro](https://altius-academy-snc.github.io/yoro/) geocoding.

Yoro Maps packages OpenStreetMap road data, map tiles, and points of interest into a single `.yoromaps` SQLite file per country. Build the file once, then route between GPS coordinates or [Yoro codes](https://altius-academy-snc.github.io/yoro/) entirely offline.

## Features

- **Offline routing** — A* shortest-path on an OSM road graph, no internet needed after build.
- **Incremental updates** — `yoromaps update` downloads only if OSM data has changed. POI and tiles are preserved.
- **In-memory graph** — Load once (~20s for Mali), route in <1s for urban routes, <7s cross-country.
- **Map tiles** — MBTiles-compatible tile storage for offline map display.
- **Yoro code integration** — Route between compact Yoro address codes directly (precision up to 1.35m).
- **Django integration** — Serve tiles and routes from a Django backend with Leaflet.
- **21 African countries** — Pre-configured Geofabrik downloads for West, Central, and East Africa.
- **Single-file databases** — One `.yoromaps` SQLite file per country, portable and deployable.

## Quick install

```bash
pip install yoro-maps
```

With optional extras:

```bash
pip install yoro-maps[django]    # Django views & router
pip install yoro-maps[tiles]     # Tile downloading (mercantile)
pip install yoro-maps[extract]   # OSM PBF extraction (pyosmium)
pip install yoro-maps[all]       # Everything
```

## Quick example

```python
import yoromaps

# Build a .yoromaps file for Mali
yoromaps.build("ML", "mali.yoromaps")

# Open and route
conn = yoromaps.open_db("mali.yoromaps")
result = yoromaps.route(conn, start_lat=12.6, start_lon=-8.0, end_lat=14.5, end_lon=-4.0)
print(f"{result.distance_km} km, {result.duration_min} min")
```

Or from the command line:

```bash
# Download and build
yoromaps download ML --output mali.yoromaps

# Route between Yoro codes
yoromaps route mali.yoromaps ML-4V7AK ML-5G62E

# Update when OSM data changes (preserves POI and tiles)
yoromaps update mali.yoromaps
```

### Tested on real data

| Route | Distance | Time |
|-------|----------|------|
| Bamako → Mopti (Mali) | 551.8 km | 6.3s |
| Bamako → Tombouctou | 812.2 km | 6.6s |
| Urban route (Bamako) | 3.8 km | 0.5s |
| Lome → Kara (Togo) | 411.8 km | 3.0s |

## Companion project

Yoro Maps is the mapping companion to the **yoro** geocoding library, which converts GPS coordinates to short, human-friendly address codes. See the [yoro documentation](https://altius-academy-snc.github.io/yoro/) for encoding/decoding, precision levels, and domains.

## Next steps

- [Installation](getting-started/install.md) — Full install guide with all extras.
- [Quick Start](getting-started/quickstart.md) — Build your first map and route.
- [Django Integration](guides/django.md) — Serve maps in a web app.
- [Countries](concepts/countries.md) — See all 21 supported countries.
