Quickstart

Routing between two points in South Africa in three steps:

1. Get a key from the Get a Key section below.
2. Send the key in the X-API-Key header on every request.
3. Call /ors/v2/directions/{profile} with start and end as lon,lat.

curl -H "X-API-Key: YOUR_KEY" \
  "https://routing.dvz.services/ors/v2/directions/driving-car?start=28.0473,-26.2041&end=18.4241,-33.9249"

Get an API Key

API keys are created from the Dashboard. Create a free account and you get 10,000 tokens every month at no cost (no card required). From there you can create, rename, reveal, copy and revoke keys, watch your usage live, and upgrade when you outgrow the free tier. See Tokens & Limits below.

Create a key on the Dashboard

Already have a key? Paste it into the Check Usage box in the sidebar to see its usage right here.

Authentication

All /ors/v2/* endpoints (except /ors/v2/health and /ors/v2/status) require an X-API-Key header. Missing or unknown keys return 401.

Tokens & Limits

Usage is metered in tokens, weighted by how heavy each call is. Every account starts with 10,000 free tokens per month, no card needed. When you run out, paid plans and once-off top-up packs are available on the Dashboard.

What each call costs

Only successful (2xx) authenticated calls are billed. Failed or unauthorized requests cost nothing. Tokens reset monthly. On the free tier your keys stop working at 0 until the next reset or an upgrade; paid plans keep serving and you simply top up.

Endpoints

curl -H "X-API-Key: YOUR_KEY" \
  "https://routing.dvz.services/ors/v2/directions/driving-car?start=28.0473,-26.2041&end=18.4241,-33.9249"

curl -X POST "https://routing.dvz.services/ors/v2/directions/driving-car" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "coordinates": [[28.0473,-26.2041], [25.6022,-33.9608], [18.4241,-33.9249]],
    "instructions": true,
    "preference": "recommended"
  }'

curl -X POST "https://routing.dvz.services/ors/v2/matrix/driving-car" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "locations": [[28.0473,-26.2041], [18.4241,-33.9249], [31.0218,-29.8587]],
    "metrics": ["distance", "duration"]
  }'

curl -X POST "https://routing.dvz.services/ors/v2/isochrones/driving-car" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "locations": [[28.0473,-26.2041]],
    "range": [600, 1800],
    "range_type": "time"
  }'

curl -X POST "https://routing.dvz.services/ors/v2/snap/driving-car" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"locations": [[28.0473,-26.2041]], "radius": 350}'

curl "https://routing.dvz.services/ors/v2/status"

curl -H "X-API-Key: YOUR_KEY" \
  "https://routing.dvz.services/geocode?q=Sandton%20City&limit=5"

{
  "query": "Sandton City",
  "provider": "pelias",
  "count": 1,
  "results": [
    {
      "lat": -26.10853,
      "lon": 28.05299,
      "display_name": "Sandton City, Sandton, GT, South Africa",
      "type": "venue",
      "importance": 0.9,
      "address": {
        "suburb": "Sandton",
        "city": "Sandton",
        "state": "GT",
        "country": "South Africa",
        "country_code": "za",
        "postcode": null
      }
    }
  ]
}

curl -H "X-API-Key: YOUR_KEY" \
  "https://routing.dvz.services/reverse?lat=-26.2041&lon=28.0473"

{
  "lat": -26.2041,
  "lon": 28.0473,
  "provider": "pelias",
  "result": {
    "lat": -26.2041,
    "lon": 28.0473,
    "display_name": "Marshalltown, Johannesburg, GT, South Africa",
    "type": "locality",
    "address": {
      "city": "Johannesburg",
      "state": "GT",
      "country": "South Africa",
      "country_code": "za"
    }
  }
}

Traffic-aware routing

A live traffic variant of driving-car for South African roads. You get a normal GeoJSON route back, but the duration reflects current congestion from TomTom plus any known incidents on the way, instead of static road speeds.

curl -X POST "https://routing.dvz.services/ors/v2/directions/driving-car-traffic" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "coordinates": [[28.0473,-26.2041], [28.1878,-25.7461]]
  }'

curl -H "X-API-Key: YOUR_KEY" \
  "https://routing.dvz.services/ors/v2/directions/driving-car-traffic?start=28.0473,-26.2041&end=28.1878,-25.7461"

What comes back

A standard GeoJSON route. summary.duration already holds the adjusted time (live traffic plus incident penalty), so you can use it as the ETA directly. The breakdown sits in properties.traffic:

"traffic": {
  "profile": "driving-car-traffic",
  "base_duration_s": 2860.4,
  "traffic_adjusted_s": 3412.9,
  "incident_penalty_s": 0.0,
  "adjusted_duration_s": 3412.9,
  "provider": "TomTomTrafficProvider",
  "incident_provider": "NullIncidentProvider",
  "incidents_on_route": []
}

Congestion rerouting

Most calls score one direct route. Alternatives are fetched and compared only when it is worth it: an incident sits on the direct route, or live traffic makes it at least 15% slower than free flow (and at least a minute slower in total). The fastest option after traffic and incidents is returned, so the geometry can differ from plain driving-car when the main road is jammed.

Free plan response

{
  "error": {
    "code": 403,
    "message": "Traffic-aware routing requires a paid plan. See /documentation/."
  }
}

A 400 is returned if start or end is not a numeric lon,lat pair.

Navigation sessions

Turn-by-turn navigation state: create a session against a route, then stream GPS fixes to it and get back a snapped position, on/off-route state, progress and ETA. A session belongs to the API key that created it; any other key gets 404 for it. To have journey events pushed to your own system instead of polling, register a webhook.

Breadcrumb (raw GPS fix) retention is off by default; an admin can enable it per API key with the Breadcrumbs toggle in the Admin panel. With it on, every fix posted to a session is stored, and the full trail can be pulled back (oldest first, paged) from the admin API at GET /admin/api/nav/sessions/{id}/track, which is useful for fleet review after a trip. The trail outlives the session so it can be fetched once the trip ends, then is swept after 24 hours; DELETE on the same path erases it immediately.

curl -X POST "https://routing.dvz.services/nav/sessions" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"coordinates": [[28.0473,-26.2041], [28.0567,-26.1076]],
       "metadata": {"driver_id": "D-114", "job_id": "JOB-9"}}'

"traffic": {
  "applied": true,
  "base_duration_s": 2635.0,
  "traffic_duration_s": 3877.0,
  "provider": "TomTomTrafficProvider"
}

curl -X POST "https://routing.dvz.services/nav/sessions/nav_abc123/updates" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fixes": [{"lon": 28.0475, "lat": -26.2039, "ts": 1734000000}]}'

{
  "session_id": "nav_8kZ2xq...",
  "snapped": { "lon": 18.4241, "lat": -33.9249, "distance_from_route_m": 12.4 },
  "on_route": true,
  "state": "ON_ROUTE",
  "progress": { "completed_m": 1520.3, "remaining_m": 7600.2, "pct": 0.1667 },
  "eta": { "arrive_at": 1737000000.0, "remaining_s": 823.9, "remaining_s_delta_vs_original": -5.2 },
  "reroute": null,
  "events": []
}

curl -X POST "https://routing.dvz.services/nav/sessions/nav_abc123/reroute" \
  -H "X-API-Key: YOUR_KEY"

Webhooks

Instead of polling journeys, give us a URL and we push journey events to it as they happen: a driver going off route, arriving, or their phone going quiet. One URL per API key; events for every journey that key creates go there. All webhook calls are free.

curl -X POST "https://routing.dvz.services/nav/webhook" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://dispatch.example.co.za/routing-events"}'

# -> { "url": "...", "secret": "whsec_...", "events": [...] }

Events

Events fire on changes, not repeatedly: a driver off route for ten minutes is one off_route, not hundreds. signal_lost is not raised before a journey's first fix or after it has arrived, since there is nothing to miss. Thresholds can be changed per journey with config when you create it.

Payload

Every event has the same shape. journey is where things stood at the moment of the event, including the metadata you sent at creation, and data holds the event-specific fields above.

{
  "id": "evt_8kZ2xq4Lm1Pq",
  "type": "journey.off_route",
  "occurred_at": "2026-10-20T08:14:03Z",
  "journey": {
    "session_id": "nav_6j4e35vzCBy4ifHZ",
    "metadata": { "driver_id": "D-114", "job_id": "JOB-9" },
    "state": "OFFROUTE",
    "position": { "lon": 28.0242, "lat": -26.1956 },
    "snapped": { "lon": 28.0280, "lat": -26.1951, "distance_from_route_m": 925.1 },
    "progress": { "completed_m": 2952.4, "remaining_m": 14201.1, "pct": 0.1721 },
    "eta": { "remaining_s": 746.0, "arrive_at": 1792451785.3 },
    "reroute_count": 1,
    "last_fix_at": "2026-10-20T08:14:03+00:00"
  },
  "data": { "distance_from_route_m": 925.1, "reroute_suggested": true }
}

eta.arrive_at is your fix's ts plus the remaining seconds, so it uses whatever clock you send. Send Unix seconds and it is a Unix timestamp.

Verifying the signature

Every request carries X-DVZ-Signature: t=<unix seconds>,v1=<hex>, where v1 is HMAC-SHA256 of "<t>.<raw body>" keyed with your secret. Check it against the raw body before parsing, and reject signatures more than five minutes old so a captured request can't be replayed. Header names are case-insensitive. Also sent: X-DVZ-Event, X-DVZ-Event-Id and X-DVZ-Delivery-Attempt.

const crypto = require("crypto");

// rawBody: the exact bytes received (Buffer), before JSON.parse
function verifyDvz(rawBody, header, secret, toleranceSec = 300) {
  const parts = Object.fromEntries((header || "").split(",").map(p => p.split("=")));
  const ts = Number(parts.t);
  if (!ts || Math.abs(Date.now() / 1000 - ts) > toleranceSec) return false;
  const expected = crypto.createHmac("sha256", secret)
    .update(ts + ".").update(rawBody).digest("hex");
  return typeof parts.v1 === "string" && parts.v1.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

import hashlib, hmac, time

def verify_dvz(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    try:
        parts = dict(p.split("=", 1) for p in header.split(","))
        ts = int(parts["t"])
    except (ValueError, KeyError, AttributeError):
        return False
    if abs(time.time() - ts) > tolerance:
        return False
    expected = hmac.new(secret.encode(), f"{ts}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

Delivery

• Reply with any 2xx within 10 seconds. Anything else (an error, a timeout or a redirect) counts as a failed attempt. Do slow work after replying.
• Retries follow after 30 s, 2 min, 10 min, 30 min, 1 h and 2 h (about 3 h 40 min in all), then the event is marked failed and the queue moves on.
• In order: events for your key arrive in the order they happened. While one is being retried, the ones behind it wait, so you never see back_on_route before off_route.
• At least once: after a timeout you may receive an event twice. Use id to ignore repeats.

Incidents

Current road incidents (crashes, closures, roadworks) as points you can draw on a map. Free to call (0 tokens), though an API key is still required. The same feed is used by driving-car-traffic, which penalises routes passing near an incident and will route around a closure.

curl -H "X-API-Key: YOUR_KEY"   "https://routing.dvz.services/incidents?bbox=27.9,-26.4,28.3,-26.0"

{
  "provider": "NullIncidentProvider",
  "count": 0,
  "incidents": []
}

{
  "id": "12345",
  "road": "N1",
  "type": "closure",
  "severity": "closure",
  "lat": -26.045,
  "lon": 28.096,
  "description": "Full closure at Buccleuch interchange"
}

Postman collection

Every endpoint above is also in our Postman collection, ready to run, with collection variables for base URL, API key and routing profile. It includes traffic routing, incidents, journey sessions and webhooks. Creating a journey session saves its id to the sessionId variable, so the follow up requests work straight away.

After importing, open the collection's Variables tab and paste your apiKey. The baseUrl defaults to production; change it to http://localhost for local dev.

Also works in Insomnia, Bruno, Hoppscotch, and most other API clients via "Import from URL" with the JSON link above.

Errors