# Quick Start

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

## 1. Install with extract support

```bash
pip install yoro-maps[extract]
```

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

```bash
pip install yoro-maps[extract,tiles]
```

## 2. Build a map database

### From the command line

```bash
# 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

```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](https://download.geofabrik.de/) and extracts the road graph. For Mali, the PBF is ~100 MB and graph extraction takes a few minutes.

## 3. Route between coordinates

```python
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

```python
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:

```bash
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:

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

```python
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

```bash
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)

```python
# 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](../guides/django.md) for Leaflet display and more.

## Next steps

- [Download & Build](../guides/download.md) — Advanced build options, using existing PBF files.
- [Routing](../guides/routing.md) — A* algorithm details, multi-leg routes, GeoJSON output.
- [Countries](../concepts/countries.md) — All 21 supported countries.
