Skip to main content
API docs by Redocly

Dawarich Atlas API (v1)

Download OpenAPI specification:Download

Local-first geocoding, routing, transit, and POI lookup. All endpoints aggregate one or more upstream OSM-derived services (Photon, Placeholder, libpostal, Valhalla, Overpass).

Geocoding

Combined forward + reverse geocoding

Unified entrypoint that auto-routes to forward or reverse:

  • ?q=… (with optional lat,lon for proximity bias) → forward search.
  • ?lat=&lon= only → reverse geocode.

Internally calls the same orchestrators as /api/v1/search and /api/v1/reverse.

query Parameters
q
string
Example: q=Marienplatz
lat
number <double>
Example: lat=48.1374
lon
number <double>
Example: lon=11.5755
limit
integer [ 1 .. 25 ]
Default: 8
lang
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Batch reverse geocoding (cached, grid-snapped)

Reverse-geocode many coordinates in one round trip.

  • Coords are snapped to a ~11 m grid (4 decimal places) when computing the cache key, so repeated lookups of points within ~11 m of each other share a result.
  • Solid Cache (Rails 8 default) memoizes results for 30 days — dawarich-style trip replays after the first run hit cache nearly 100%.
  • Hard cap: 500 coords per request. For larger inputs, page client-side.
  • Each result preserves the caller's optional id so clients can correlate.
Request Body schema: application/json
required
Array of objects <= 500 items
lang
string or null

Responses

Request samples

Content type
application/json
{
  • "coords": [
    ],
  • "lang": "de"
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Reverse geocoding (point → labeled feature + admin chain)

Sequential pipeline:

  1. Photon reverse → nearest labeled feature + its own admin tags.
  2. Placeholder fills in missing admin chain when Photon's tags are thin.
query Parameters
lat
required
number <double>
Example: lat=52.5163
lon
required
number <double>
Example: lon=13.3777
lang
string
Example: lang=de

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Forward geocoding (autocomplete + admin enrichment)

Sequential pipeline:

  1. libpostal normalizes the query.
  2. Photon returns ranked candidates.
  3. Placeholder fills in missing admin chain (country / state / city) per candidate.

Returns gracefully when Photon is down: data: [], meta.upstream: "unavailable".

query Parameters
q
required
string
Example: q=Marienplatz
limit
integer [ 1 .. 25 ]
Default: 8
lang
string
Example: lang=de
lat
number <double>

Optional proximity bias

lon
number <double>

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Routing

Routing via Valhalla (multimodal)

Single-source endpoint — Valhalla returns a turn-by-turn route, summary, and (optional) elevation profile.

query Parameters
from
required
string^-?\d+(\.\d+)?,-?\d+(\.\d+)?$
Example: from=52.5163,13.3777

lat,lon

to
required
string^-?\d+(\.\d+)?,-?\d+(\.\d+)?$
Example: to=48.1374,11.5755

lat,lon

mode
string
Default: "auto"
Enum: "auto" "bicycle" "pedestrian"

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Snap a recorded GPS trace onto the road network

Returns every matched segment and one correlation result per input point. Supply timestamps and accuracy when available. GeoJSON uses a MultiLineString when the trace contains discontinuities. Directions are optional because they require a second Valhalla request.

Request Body schema: application/json
required
required
Array of objects >= 2 items
mode
string
Enum: "auto" "bicycle" "pedestrian"
shape_match
string
Enum: "map_snap" "walk_or_snap" "edge_walk"
format
string
Enum: "polyline6" "geojson"
include_directions
boolean
Default: false

Include narrative paths using an additional trace_route request.

search_radius
number
gps_accuracy
number
breakage_distance
number

Responses

Request samples

Content type
application/json
{
  • "shape": [
    ],
  • "mode": "auto",
  • "shape_match": "map_snap",
  • "format": "polyline6",
  • "include_directions": false,
  • "search_radius": 35,
  • "gps_accuracy": 5,
  • "breakage_distance": 2000
}

Response samples

Content type
application/json
Example
{
  • "data": {
    },
  • "meta": {
    }
}

POIs

Reverse + nearby POIs in a radius

Combines ReverseOrchestrator (Photon reverse + Placeholder admin enrichment) with an Overpass radius query so a single call answers “what is at and around this point”.

query Parameters
lat
required
number <double>
Example: lat=52.5163
lon
required
number <double>
Example: lon=13.3777
radius
integer [ 10 .. 2000 ]
Default: 200
lang
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

List points of interest in a bounding box

query Parameters
bbox
required
string
Example: bbox=52.50,13.36,52.54,13.42

south,west,north,east

types
string
Example: types=cafe,restaurant
q
string
Example: q=breakfast
limit
integer [ 1 .. 1000 ]
Example: limit=100
lang
string
Example: lang=en

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

List the POI category catalog

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Transit

Plan a public-transport journey

Uses the selected transit engine (MOTIS by default, or OpenTripPlanner). The normalized Atlas response has the same shape for both engines.

query Parameters
from
required
string
Example: from=52.4884,13.4703

Origin as lat,lon

to
required
string
Example: to=52.5073,13.3324

Destination as lat,lon

time
string <date-time>
Example: time=2026-09-07T08:00:00Z

ISO 8601 departure or arrival time

modes
string
Example: modes=TRANSIT,WALK
num
integer [ 1 .. 6 ]
Example: num=3
arrive_by
boolean

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

System

Return the running Atlas version and revision

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Return health for each public capability

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Photon passthrough

Raw Photon forward-geocoding passthrough

Compatibility endpoint. Query parameters are forwarded to Photon unchanged.

Responses

Response samples

Content type
application/json
{
  • "type": "FeatureCollection",
  • "features": [
    ]
}

Raw Photon reverse-geocoding passthrough

Responses

Response samples

Content type
application/json
{
  • "type": "FeatureCollection",
  • "features": [
    ]
}

Raw Photon lookup-by-OSM-id passthrough

Responses

Response samples

Content type
application/json
{
  • "type": "FeatureCollection",
  • "features": [
    ]
}

Raw Photon status passthrough

Responses

Response samples

Content type
application/json
{
  • "status": "ok"
}