# 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://pypi.org/project/yoro/) geocoding.

## Install

```bash
pip install yoro-maps
pip install yoro-maps[extract]  # OSM data extraction
pip install yoro-maps[django]   # Django integration
pip install yoro-maps[tiles]    # Tile downloading
```

## Build a map database

```bash
yoromaps download ML --output mali.yoromaps
```

## Route between Yoro codes

```bash
yoromaps route mali.yoromaps ML-4V7AK ML-5G62E
```

```python
import yoromaps

conn = yoromaps.open_db("mali.yoromaps")
graph = yoromaps.Graph.from_db(conn)  # load once

r = graph.route(12.639, -8.003, 14.489, -4.197)  # Bamako → Mopti
print(f"{r.distance_km} km, {r.duration_min} min")  # 551.8 km, 681.0 min
```

## Update maps

```bash
yoromaps update mali.yoromaps
# → Downloads only if OSM data has changed. POI and tiles are preserved.
```

## Tested performance

| Route | Distance | Compute |
|-------|----------|---------|
| Bamako → Mopti | 551.8 km | 6.3s |
| Bamako → Tombouctou | 812.2 km | 6.6s |
| Urban (Bamako) | 3.8 km | 0.5s |

## Django integration

```python
import yoromaps

DATABASES = {
    "default": { ... },
    "maps": yoromaps.db_config("/data/mali.yoromaps"),
}
DATABASE_ROUTERS = ["yoromaps.django.router.YoroMapsRouter"]
```

## License

MIT — Paul Guindo / Altius Academy SNC.
