Yoro Maps

Documentation | PyPI | GitHub

Offline maps, routing, and POI for Africa — companion to yoro geocoding.

Install

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

yoromaps download ML --output mali.yoromaps

Route between Yoro codes

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

import yoromaps

conn = yoromaps.open_db("mali.yoromaps")
graph = yoromaps.get_graph("mali.yoromaps")  # loaded once, cached per process

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

# Points of interest — every POI gets a Yoro code automatically
poi = yoromaps.add_poi(conn, 12.639, -8.002, "Grand marche", category="market")
print(poi["yoro_code"])                              # "ML-4V7AK"
yoromaps.pois_near(conn, 12.64, -8.0, radius_m=500)  # sorted by distance
yoromaps.pois_in_cell(conn, "ML-4V7AK")              # who lives at this address?

A build already fills that table from OpenStreetMap: the shops, schools, hospitals, markets and places of worship in the extract are read out, given their Yoro code and stored under source="osm". Re-running an extraction replaces only those rows, so locally added POIs survive every refresh.

from yoromaps.osm_poi import extract_pois, categorize

categorize({"amenity": "pharmacy"})   # "pharmacy"
categorize({"amenity": "parking"})    # None — not every tag is a place

stats = extract_pois("togo-latest.osm.pbf", conn)
stats["pois"]        # 16940
stats["unmapped"]    # the tags we walked past, most frequent first

Tagging is an allowlist, so noise stays out; stats["unmapped"] is what tells you which categories are worth adding next. Nameless features are skipped.

yoromaps download ML -o mali.yoromaps --no-pois   # routing graph only

Update maps

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

Tested performance

Django integration

import yoromaps

DATABASES = {
    "default": { ... },
    "maps": yoromaps.db_config("/data/mali.yoromaps"),
}

License

MIT — Paul Guindo / Altius Academy SNC.