Skip to content

Django API Reference

yoromaps.django

Django integration package. Add "yoromaps.django" to INSTALLED_APPS.

yoromaps.django

Yoro Maps Django integration.

Add to your settings::

import yoromaps

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

DATABASES = {
    "default": { ... },
    "maps": yoromaps.db_config("/path/to/country.yoromaps"),
}

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

yoromaps.django.views

Django views for tile serving and routing.

yoromaps.django.views

Django views for yoro-maps — tile serving and routing API.

tile_view(request, z, x, y)

Serve a map tile from the .yoromaps database.

GET /maps/tiles/{z}/{x}/{y}.png

Source code in src/yoromaps/django/views.py 
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
@require_GET
def tile_view(request, z, x, y):
    """Serve a map tile from the .yoromaps database.

    ``GET /maps/tiles/{z}/{x}/{y}.png``
    """
    db_path = _get_maps_db()
    if not db_path:
        return HttpResponse(status=404)

    conn = sqlite3.connect(db_path)
    conn.row_factory = sqlite3.Row
    data = get_tile(conn, int(z), int(x), int(y))
    conn.close()

    if data:
        resp = HttpResponse(data, content_type="image/png")
        resp["Cache-Control"] = "public, max-age=86400"
        return resp
    return HttpResponse(status=404)

route_view(request)

Calculate a route between Yoro codes.

GET /maps/route/?codes=ML-ABC,ML-XYZ

Source code in src/yoromaps/django/views.py 
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
@require_GET
def route_view(request):
    """Calculate a route between Yoro codes.

    ``GET /maps/route/?codes=ML-ABC,ML-XYZ``
    """
    import yoro

    codes_str = request.GET.get("codes", "")
    codes = [c.strip() for c in codes_str.split(",") if c.strip()]

    if len(codes) < 2:
        return JsonResponse({"error": "At least 2 Yoro codes required"}, status=400)

    db_path = _get_maps_db()
    if not db_path:
        return JsonResponse({"error": "Maps database not configured"}, status=500)

    conn = sqlite3.connect(db_path)
    conn.row_factory = sqlite3.Row

    try:
        legs = route_from_codes(conn, codes)
    except ValueError as e:
        conn.close()
        return JsonResponse({"error": str(e)}, status=400)

    conn.close()

    total_km = sum(leg.distance_km for leg in legs)
    total_min = sum(leg.duration_min for leg in legs)

    return JsonResponse({
        "total_distance_km": total_km,
        "total_duration_min": total_min,
        "legs": [
            {
                "distance_km": leg.distance_km,
                "duration_min": leg.duration_min,
                "found": leg.found,
                "geometry": leg.geometry,
                "steps": leg.steps,
            }
            for leg in legs
        ],
    })

yoromaps.django.router

Database router for directing yoromaps queries to the maps database.

yoromaps.django.router

Database router that sends tile/routing queries to the maps SQLite database.

Usage in settings.py::

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

YoroMapsRouter

Route read queries for yoromaps models to the 'maps' database.

Source code in src/yoromaps/django/router.py 
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
class YoroMapsRouter:
    """Route read queries for yoromaps models to the 'maps' database."""

    def db_for_read(self, model, **hints):
        if model._meta.app_label == "yoromaps":
            return "maps"
        return None

    def db_for_write(self, model, **hints):
        if model._meta.app_label == "yoromaps":
            return "maps"
        return None

    def allow_relation(self, obj1, obj2, **hints):
        return None

    def allow_migrate(self, db, app_label, model_name=None, **hints):
        if app_label == "yoromaps":
            return db == "maps"
        if db == "maps":
            return False
        return None

yoromaps.django.urls

URL configuration. Include with:

path("maps/", include("yoromaps.django.urls"))

Registered URL patterns

Pattern Name View
tiles/<int:z>/<int:x>/<int:y>.png tile tile_view
route/ route route_view

yoromaps.django.apps

yoromaps.django.apps

YoroMapsConfig

Bases: AppConfig

Source code in src/yoromaps/django/apps.py 
4
5
6
7
8
class YoroMapsConfig(AppConfig):
    name = "yoromaps.django"
    label = "yoromaps"
    verbose_name = "Yoro Maps"
    default_auto_field = "django.db.models.BigAutoField"