Quick Start

This guide walks through building a .yoromaps file and running your first route.

1. Install with extract support

pip install yoro-maps[extract]

The extract extra is needed to parse OSM data. If you also want map tiles, install tiles too:

pip install yoro-maps[extract,tiles]

2. Build a map database

From the command line

# Download OSM data for Mali and build the road graph
yoromaps download ML --output mali.yoromaps

# With map tiles (slower, ~200+ MB depending on zoom level)
yoromaps download ML --output mali.yoromaps --tiles --zoom-max 14

From Python

import yoromaps

# Build road graph only
yoromaps.build("ML", "mali.yoromaps")

# With tiles
yoromaps.build("ML", "mali.yoromaps", include_tiles=True, zoom_max=14)

Tip

The download fetches the latest OSM PBF from Geofabrik and extracts the road graph. For Mali, the PBF is ~100 MB and graph extraction takes a few minutes.

3. Route between coordinates

import yoromaps

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"Distance: {result.distance_km} km")
print(f"Duration: {result.duration_min} min")
print(f"Found:    {result.found}")
print(f"Steps:    {len(result.steps)}")

4. Route between Yoro codes

import yoromaps

conn = yoromaps.open_db("mali.yoromaps")
legs = yoromaps.route_from_codes(conn, ["ML-ABC", "ML-XYZ"])

for i, leg in enumerate(legs):
    print(f"Leg {i + 1}: {leg.distance_km} km, {leg.duration_min} min")

From the CLI:

yoromaps route mali.yoromaps ML-ABC ML-XYZ

Output is JSON with distance, duration, and turn-by-turn steps.

5. Update the map data

Keep the road graph up to date without re-downloading everything:

yoromaps update mali.yoromaps
# → Downloads only if Geofabrik has a newer PBF
# → "Already up to date" if nothing changed (instant)

result = yoromaps.update("mali.yoromaps")
if result["updated"]:
    print(f"Updated: {result['nodes']:,} nodes")

Updates preserve your POI data and tiles — only the road graph is rebuilt.

6. Inspect the database

yoromaps info mali.yoromaps

Database: mali.yoromaps
  country: ML
  country_name: Mali
  graph_nodes: 6,435,580
  graph_edges: 6,699,069
  osm_update_date: Mon, 17 Mar 2026 00:00:00 GMT

7. Django integration (optional)

# settings.py
import yoromaps

INSTALLED_APPS = [..., "yoromaps.django"]

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

DATABASE_ROUTERS = ["yoromaps.django.router.YoroMapsRouter"]

# urls.py
from django.urls import path, include

urlpatterns = [
    path("maps/", include("yoromaps.django.urls")),
]

This gives you:

• GET /maps/tiles/{z}/{x}/{y}.png — serve map tiles
• GET /maps/route/?codes=ML-ABC,ML-XYZ — calculate routes

See the full Django Integration guide for Leaflet display and more.

Next steps

• Download & Build — Advanced build options, using existing PBF files.
• Routing — A* algorithm details, multi-leg routes, GeoJSON output.
• Countries — All 21 supported countries.