Farun API Reference

This is the complete reference for the Farun self-hosted server. It exposes vector tile serving, address and place search powered by Elasticsearch, and a full routing engine backed by Valhalla - covering turn-by-turn directions, isochrones, elevation profiles, time/distance matrices, optimised routes, and map matching.

Endpoint index

Base URL & Configuration

All endpoints are relative to the server root. No path prefix. Default port is 3000, configurable via the PORT environment variable.

# Self-hosted Farun Tile + Routing Server
http://your-host          # replace with your actual host

# Default port (configurable via PORT env var)
http://your-host:3000

# FastAPI auto-generated interactive docs also available at:
http://your-host/docs     # Swagger UI
http://your-host/redoc    # ReDoc

Environment variables

Status Codes

Server liveness check. No parameters. Suitable for load-balancer health probes.

curl http://your-host/health

Response (200 OK)

{ "status": "ok", "uptime": "142s" }

Lists all .mbtiles files loaded from MBTILES_DIR, with metadata and tile URL templates.

curl http://your-host/sources

Source object fields

{
  "sources": [{
    "id":          "south_africa",
    "name":        "South Africa Streets",
    "description": "OSM extract",
    "format":      "pbf",
    "minzoom":     0,
    "maxzoom":     14,
    "bounds":      "16.3,-34.9,32.9,-22.1",
    "center":      "25.0,-29.0,6",
    "tiles":       "http://your-host/tiles/south_africa/{z}/{x}/{y}",
    "tilejson":    "http://your-host/tiles/south_africa"
  }]
}

Returns a TileJSON 3.0.0 document. The recommended way to integrate with MapLibre GL or Mapbox GL - pass this URL as the source url and the renderer auto-configures itself.

Path parameters

curl http://your-host/tiles/south_africa

map.addSource('farun', {
  type: 'vector',
  url:  'http://your-host/tiles/south_africa'
});

Additional response fields vs /sources

Fetches a single Mapbox Vector Tile (PBF). XYZ convention - TMS y-flip is handled internally. In-memory LRU cache of 200,000 tiles.

Path parameters

curl -o tile.pbf http://your-host/tiles/south_africa/10/567/432

const res = await fetch('http://your-host/tiles/south_africa/10/567/432');
// 204 = empty tile (normal for ocean / sparse areas)
if (res.status === 200) {
  const buffer = await res.arrayBuffer();
}

map.addSource('farun', {
  type:    'vector',
  tiles:   ['http://your-host/tiles/south_africa/{z}/{x}/{y}'],
  minzoom: 0,
  maxzoom: 14
});

Response headers (200)

Status codes

Looks up and returns a pre-rendered JPEG from the static cache directory. Cache lookup only - does not render on demand. Returns 404 if no matching image exists.

Request body (JSON)

curl -X POST http://your-host/static \
  -H 'Content-Type: application/json' \
  -d '{"center":[18.4241,-33.9249],"zoom":12,"tile_source":"south_africa"}' \
  --output map.jpg

const res = await fetch('http://your-host/static', {
  method:  'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    center:      [18.4241, -33.9249],
    zoom:        12,
    width:       1024,
    height:      768,
    tile_source: 'south_africa'
  })
});
if (res.ok) {
  const blob = await res.blob(); // JPEG
}

Status codes

Autocomplete-optimised full-text search powered by Elasticsearch. Sub-20ms latency. Safe to call on every keystroke after 2 characters.

Query parameters

# Basic search
curl 'http://your-host/search?q=Cape+Town'

# With type filter + proximity bias
curl 'http://your-host/search?q=Bree+Street&types=street,address&lat=-33.92&lon=18.42&size=5'

const params = new URLSearchParams({
  q: 'Bree Street', types: 'street,address',
  lat: -33.92, lon: 18.42, size: 5
});
const data = await fetch(`http://your-host/search?${params}`).then(r => r.json());

Result object fields

{
  "query":   "Cape Town",
  "total":   142,
  "took_ms": 8,
  "results": [{
    "id":           "abc123",
    "score":        24.871,
    "doc_type":     "place",
    "display_name": "Cape Town, Western Cape, ZA",
    "location":     { "lat": -33.9249, "lon": 18.4241 }
  }]
}

Finds the nearest addresses or places to a coordinate. Only documents within 2 km are considered. Results sorted by distance ascending.

Query parameters

curl 'http://your-host/search/reverse?lat=-33.9249&lon=18.4241&size=3&types=address'

Additional response field

{
  "lat": -33.9249, "lon": 18.4241, "took_ms": 5,
  "results": [{
    "id":           "xyz789",
    "doc_type":     "address",
    "display_name": "12 Bree Street, Cape Town, 8000",
    "distance_m":   34.2,
    "location":     { "lat": -33.9247, "lon": 18.4238 }
  }]
}

Returns the full document for a single result ID - including the GeoJSON geometry and wikidata fields that are excluded from list responses. Call only when a user selects a result.

Path parameters

curl http://your-host/search/detail/abc123

Additional fields beyond list result

{
  "id": "abc123",  "doc_type": "place",
  "display_name": "Cape Town, Western Cape, ZA",
  "location": { "lat": -33.9249, "lon": 18.4241 },
  "geometry": { "type": "Point", "coordinates": [18.4241, -33.9249] },
  "wikidata": "Q5465"
}

Returns all available transport modes (costings) and their descriptions. Use these IDs as the costing field in routing requests.

curl http://your-host/costings

{
  "costings": [
    { "id": "auto",          "name": "Car",            "description": "Fastest car route" },
    { "id": "auto_shorter",  "name": "Car (shortest)", "description": "Shortest distance" },
    { "id": "truck",         "name": "Truck/HGV",     "description": "Heavy goods" },
    { "id": "bicycle",       "name": "Bicycle",       "description": "Cycling" },
    { "id": "pedestrian",    "name": "Walking",       "description": "On foot" },
    { "id": "motorcycle",    "name": "Motorcycle",    "description": "Motorbike" },
    { "id": "motor_scooter", "name": "Scooter",       "description": "Scooter" },
    { "id": "bus",           "name": "Bus",           "description": "Bus" },
    { "id": "taxi",          "name": "Taxi",          "description": "Taxi" }
  ]
}

Returns the full JSON Schema of available options for a transport mode. Use the returned field names as keys in the costing_options body of routing requests.

Path parameters

Turn-by-turn directions between two or more waypoints. Returns route geometry, step instructions, distance, and duration. Supports up to 3 alternative routes.

Request body (JSON)

Location Object

curl -X POST http://your-host/route \
  -H 'Content-Type: application/json' \
  -d '{
    "locations": [
      {"lon": 18.4241, "lat": -33.9249},
      {"lon": 18.8602, "lat": -33.9321}
    ],
    "costing": "auto"
  }'

const data = await fetch('http://your-host/route', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    locations: [
      { lon: 18.4241, lat: -33.9249 },
      { lon: 18.8602, lat: -33.9321 }
    ],
    costing:    'auto',
    alternates: 2,          // up to 3 alternative routes
    directions_options: { units: 'kilometers', language: 'en-US' }
  })
}).then(r => r.json());

Generates reachability polygons from a single origin point. Contours can be time-based (minutes) or distance-based (kilometres) - not both in the same request. Returns GeoJSON FeatureCollection.

Request body (JSON)

# Time-based (minutes)
curl -X POST http://your-host/isochrone \
  -H 'Content-Type: application/json' \
  -d '{
    "locations": [{"lon": 18.4241, "lat": -33.9249}],
    "costing": "auto",
    "contours": [{"time": 15}, {"time": 30}, {"time": 45}],
    "polygons": true,
    "generalize": 50
  }'

# Distance-based (kilometres)
curl -X POST http://your-host/isochrone \
  -H 'Content-Type: application/json' \
  -d '{
    "locations": [{"lon": 18.4241, "lat": -33.9249}],
    "costing": "pedestrian",
    "contours": [{"distance": 2}, {"distance": 5}]
  }'

const data = await fetch('http://your-host/isochrone', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    locations: [{ lon: 18.4241, lat: -33.9249 }],
    costing:   'auto',
    contours:  [{ time: 15 }, { time: 30 }, { time: 45 }],
    polygons:  true,
    denoise:   1,
    generalize:50
  })
}).then(r => r.json());

Returns terrain elevation for a series of coordinates along a path. Input can be a coordinate array or an encoded polyline string.

Request body (JSON)

# Shape as coordinate array
curl -X POST http://your-host/elevation \
  -H 'Content-Type: application/json' \
  -d '{
    "shape": [
      {"lon": 18.4241, "lat": -33.9249},
      {"lon": 18.5000, "lat": -33.9500},
      {"lon": 18.8602, "lat": -33.9321}
    ],
    "range": true
  }'

# Encoded polyline (polyline6)
curl -X POST http://your-host/elevation \
  -H 'Content-Type: application/json' \
  -d '{"encoded_polyline": "qp~IvskA...", "range": true}'

Computes a many-to-many time and distance matrix between any number of source and target locations. Returns travel time and distance for every source→target pair.

Request body (JSON)

curl -X POST http://your-host/matrix \
  -H 'Content-Type: application/json' \
  -d '{
    "sources": [{"lon": 18.4241, "lat": -33.9249}],
    "targets": [
      {"lon": 18.8602, "lat": -33.9321},
      {"lon": 18.5500, "lat": -33.9800}
    ],
    "costing": "auto",
    "units": "kilometers"
  }'

Solves the Travelling Salesman Problem - finds the optimal visit order for a set of locations to minimise total route cost. Returns a full route with the reordered stops.

Request body (JSON)

curl -X POST http://your-host/optimised_route \
  -H 'Content-Type: application/json' \
  -d '{
    "locations": [
      {"lon": 18.4241, "lat": -33.9249},
      {"lon": 18.8602, "lat": -33.9321},
      {"lon": 18.5500, "lat": -33.9800},
      {"lon": 18.6700, "lat": -34.0100}
    ],
    "costing": "auto"
  }'

Snaps a raw GPS trace to the most likely path on the road network. Returns a cleaned route with turn-by-turn directions. Useful for post-processing recorded vehicle or device tracks.

Request body (JSON)

curl -X POST http://your-host/map_match \
  -H 'Content-Type: application/json' \
  -d '{
    "shape": [
      {"lon": 18.4241, "lat": -33.9249, "time": 0},
      {"lon": 18.5000, "lat": -33.9500, "time": 30},
      {"lon": 18.8602, "lat": -33.9321, "time": 90}
    ],
    "costing": "auto",
    "shape_match": "map_snap"
  }'

Same input as /map_match but returns detailed edge-level attributes for each matched road segment - speed limits, surface type, road class, and more. Useful for road quality analysis and insurance telematics.

Accepts the same request body as /map_match.