Skip to content

Yoro Maps

Documentation | PyPI | GitHub

Offline maps, routing, and POI for Africa — companion to 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 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

pip install yoro-maps

With optional extras:

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

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:

# 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 for encoding/decoding, precision levels, and domains.

Next steps