Skip to main content
API docs by Redocly

Apocalymaps API (v1)

Download OpenAPI specification:Download

Local-first geocoding, routing, 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": {
    }
}

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": {
    }
}