Routing API · Playground

Quickstart

Routing between two points in South Africa - three steps:

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

curl

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

Self-serve. The key is shown once - copy it now and save it somewhere safe. You can always check your usage later by pasting the key in the sidebar.

Authentication

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

Base URL

https://routing.dvz.services

Rate limit

30 requests/sec per key. Bursts beyond return 429.

Profiles

driving-car, foot-walking

Endpoints

GET /ors/v2/directions/{profile} - Route between two points

Returns a single best route as GeoJSON with turn-by-turn instructions.

Query params

Name	Type	Required	Description
`start`	string	yes	Start `lon,lat`
`end`	string	yes	End `lon,lat`

Example

curl

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"

POST /ors/v2/directions/{profile} - Advanced routing

Multiple waypoints, alternative routes, preferences, full options.

Example

curl

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"
  }'

POST /ors/v2/matrix/{profile} - N-to-N distance + duration

Computes all-pairs distance and duration between up to 150 locations.

Example

curl

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"]
  }'

POST /ors/v2/isochrones/{profile} - Reach polygons

Areas reachable from a point within given times or distances.

Example

curl

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"
  }'

POST /ors/v2/snap/{profile} - Snap points to road network

Snap arbitrary lon/lat points to the nearest road within a radius.

Example

curl

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}'

GET /ors/v2/health - Engine health public

Returns {"status": "ready"} when the routing engine is up. No API key required - useful for monitoring.

GET /geocode - Forward geocode (address → coordinates)

Takes a free-text address or place name and returns ranked coordinate matches. Powered by self-hosted Photon (Komoot, OSM-based). Response is a stable DVZ envelope regardless of upstream provider.

Query params

Name	Type	Required	Description
`q`	string	yes	Free-text address or place name (1–200 chars)
`limit`	int	no	Max results, 1–20 (default 5)
`country`	string	no	ISO-3166-1 alpha-2 country bias. Defaults to `za`. Pass empty string for worldwide.

Example

curl

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

Response shape

JSON

{
  "query": "Sandton, Johannesburg",
  "provider": "photon",
  "count": 1,
  "results": [
    {
      "lat": -26.107568,
      "lon": 28.057222,
      "display_name": "Sandton, Johannesburg, Gauteng, South Africa",
      "type": "city",
      "importance": null,
      "address": {
        "suburb": "Sandton",
        "city": "Johannesburg",
        "state": "Gauteng",
        "country": "South Africa",
        "country_code": "za",
        "postcode": null
      }
    }
  ]
}

GET /reverse - Reverse geocode (coordinates → address)

Takes a lat/lon point and returns the closest matching address. Same DVZ envelope as /geocode but for a single point.

Query params

Name	Type	Required	Description
`lat`	float	yes	Latitude, –90 to 90
`lon`	float	yes	Longitude, –180 to 180

Example

curl

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

Response shape

JSON

{
  "lat": -26.2041,
  "lon": 28.0473,
  "provider": "photon",
  "result": {
    "lat": -26.2041,
    "lon": 28.0473,
    "display_name": "Johannesburg, Gauteng, South Africa",
    "type": "city",
    "address": {
      "city": "Johannesburg",
      "state": "Gauteng",
      "country": "South Africa",
      "country_code": "za"
    }
  }
}

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.

Run in Postman Download JSON

After importing, open the collection's Variables tab and paste your apiKey. The baseUrl defaults to production - change 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

Status	Meaning	What to do
`401`	Missing / unknown / revoked API key	Check your key. Generate a fresh one above if it was revoked.
`429`	Rate limit exceeded (30 req/sec)	Add client-side throttling or request a higher limit.
`400`	Bad request (malformed body, invalid params)	Check the example for that endpoint.
`500/502/503`	Engine unavailable	Check `/ors/v2/health` - if it's down, contact the team.