API docs for this instance

back to the map

All paths are relative to this origin: . The tester forwards them to the configured instances; the services themselves need no domain of their own. Anything greyed out here was not configured in the template. This page covers what the tester exposes and how to call it; each section links to the full upstream reference, and the version line under each heading is read live from the running service.

Vector Tiles
Nominatim (geocoding)
Valhalla (routing)
Overpass API
If the domain is protected with Basic Auth (Hosting), it applies to every path. For scripts use curl -u user:password …; in the browser avoid https://user:password@… and send an Authorization header instead.

Vector Tiles

Deployed: loading

One PMTiles archive in the Protomaps basemap schema, zoom 0 to 15, built by the osm-tiles template with pmtiles extract from the daily Protomaps planet build. Three ways to use it:

PathPurpose
/style.jsonready-made MapLibre style (Protomaps light), pointing at this origin
/tiles//{z}/{x}/{y}.mvtsingle tiles (ZXY), 204 outside the region
/the archive itself, readable with HTTP range requests (pmtiles protocol)
/fonts/{fontstack}/{range}.pbfglyphs: Noto Sans Regular, Medium, Italic
/sprites/light, /sprites/darksprites (json, png, @2x)
/viewer/maplibre-gl.js, /viewer/pmtiles.jsbrowser libraries, served from here
/status.jsonregion, Protomaps build date, ready flag of the tiles instance

Full reference: Protomaps basemap layers and fields, PMTiles format and protocol, MapLibre style spec, MapLibre GL JS API. Data refresh: pick a newer build date in the osm-tiles instance under Configure.

MapLibre, shortest path

<link rel="stylesheet" href="/viewer/maplibre-gl.css">
<script src="/viewer/maplibre-gl.js"></script>
<div id="map" style="height:100vh"></div>
<script>
  new maplibregl.Map({ container: "map", style: "/style.json", center: [10.45, 51.16], zoom: 6 });
</script>

Archive directly (pmtiles protocol, your own style)

<script src="/viewer/pmtiles.js"></script>
maplibregl.addProtocol("pmtiles", new pmtiles.Protocol().tile);
// in the style: sources.protomaps.url = "pmtiles:///"

What is inside

Layers pois, places, roads, buildings, landuse, water, earth, landcover, boundaries with the Protomaps schema fields (kind, kind_detail, name, height on buildings). No OSM ids and no full tag sets: that is what Overpass is for. landuse carries no names; named parks live in pois.

curl -sI -r 0-1023 /   # must answer 206
curl -s /style.json | head -c 300

Nominatim: addresses and places

Deployed: loading

Same API as nominatim.openstreetmap.org, base /api/nominatim. Nominatim itself sends no CORS headers; through this origin browser calls work anyway.

EndpointPurpose
GET /api/nominatim/search?q=…&format=jsonv2&limit=5search by address or place name. Optional viewbox=lon1,lat1,lon2,lat2 with bounded=1, accept-language=de, addressdetails=1, extratags=1
GET /api/nominatim/reverse?lat=…&lon=…&format=jsonv2address for coordinates, zoom=18 for house numbers, zoom=10 for the city
GET /api/nominatim/lookup?osm_ids=N123,W456,R789&format=jsonv2objects by OSM id (type prefix N, W, R)
GET /api/nominatim/search?street=…&city=…&postalcode=…&country=…structured search instead of free text (amenity, street, city, county, state, country, postalcode)
GET /api/nominatim/details?osmtype=N&osmid=…&format=jsoneverything Nominatim knows about one object: hierarchy, keywords, linked places
GET /api/nominatim/status?format=jsonversion and data timestamp

Useful parameters on search and reverse: polygon_geojson=1 for outlines, countrycodes=de,at, layer=address,poi, dedupe=0, namedetails=1, extratags=1 (Wikipedia, website, opening hours when tagged). Output formats: jsonv2 (recommended), json, geojson, geocodejson, xml.

Full reference: Nominatim API (Search, Reverse, Lookup, Details, Status), output formats. Not available on this instance: updates are off (data frozen at import), and the special phrases for category search are not imported.

curl -s "/api/nominatim/search?q=Unter+den+Linden+1,+Berlin&format=jsonv2&limit=1"
curl -s "/api/nominatim/reverse?lat=52.5163&lon=13.3777&format=jsonv2"
const r = await fetch(`/api/nominatim/search?${new URLSearchParams({ q, format: "jsonv2", limit: "5", "accept-language": "de" })}`);
const hits = await r.json();   // [{ lat, lon, display_name, type, address, … }]
No category search: q=cafe finds objects with "cafe" in their name, not every cafe nearby. For "what is around here" use Overpass.

Valhalla: routing

Deployed: loading

Same API as any Valhalla server, base /api/routing. Requests are JSON via POST. Costings: pedestrian, bicycle, auto, truck, motorcycle, bus.

EndpointPurpose
POST /api/routing/routeroute with turn-by-turn instructions. directions_options.language: "de-DE" for German text
POST /api/routing/isochronereachability in minutes or kilometres as GeoJSON
POST /api/routing/sources_to_targetsdistance matrix
POST /api/routing/trace_route, trace_attributesmap matching of a GPS trace
POST /api/routing/locatenearest road edge to a point
POST /api/routing/optimized_routebest visiting order for several stops
POST /api/routing/heightelevation along a shape (only if the graph was built with elevation, which this template does not)
POST /api/routing/expansion, centroidgraph expansion as GeoJSON, meeting point for several origins
GET /api/routing/status?verbose=trueversion, data timestamp, available actions

Common options: costing_options per costing (for example {"pedestrian":{"walking_speed":5.1}}), alternates, units: "kilometers", directions_options.language, date_time for time-dependent restrictions, exclude_locations, avoid_polygons.

Full reference: Valhalla API (turn-by-turn, isochrone, matrix, map matching, locate, elevation, expansion, status), route request and response fields. Transit and elevation are not built on this instance.

curl -s -X POST /api/routing/route -d '{
  "locations": [{ "lat": 52.5200, "lon": 13.4050 }, { "lat": 52.5163, "lon": 13.3777 }],
  "costing": "pedestrian",
  "directions_options": { "language": "de-DE", "units": "kilometers" }
}'

trip.summary.length is in km, trip.summary.time in seconds. The geometry trip.legs[].shape is a polyline with 6 decimal places:

function decodePolyline6(str) {
  const out = []; let i = 0, lat = 0, lon = 0;
  while (i < str.length) {
    let s = 0, r = 0, b;
    do { b = str.charCodeAt(i++) - 63; r |= (b & 0x1f) << s; s += 5; } while (b >= 0x20);
    lat += r & 1 ? ~(r >> 1) : r >> 1; s = 0; r = 0;
    do { b = str.charCodeAt(i++) - 63; r |= (b & 0x1f) << s; s += 5; } while (b >= 0x20);
    lon += r & 1 ? ~(r >> 1) : r >> 1;
    out.push([lon / 1e6, lat / 1e6]);
  }
  return out;
}
curl -s -X POST /api/routing/isochrone -d '{
  "locations": [{ "lat": 52.52, "lon": 13.405 }],
  "costing": "bicycle", "contours": [{ "time": 10 }], "polygons": true
}'

Overpass API: every tag

Deployed: loading

Same API as overpass-api.de, base /api/overpass. Overpass QL, results as JSON with [out:json]. This is where you get what the tiles leave out: opening hours, websites, Wikipedia links, construction years, complete tag sets.

EndpointPurpose
POST /api/overpass/api/interpreter with data=<QL>query (preferred, no URL length limit)
GET /api/overpass/api/interpreter?data=<QL, URL-encoded>query via GET
GET /api/overpass/api/statusserver status, slots, running queries
GET /api/overpass/api/timestampdata timestamp
GET /api/overpass/api/kill_my_queriescancel your running queries

Query building blocks: global settings [out:json][timeout:25][bbox:south,west,north,east]; selectors node, way, relation, nwr with filters [amenity=cafe], [name~"^Caf",i], (around:r,lat,lon), (bbox), (id); output out;, out tags;, out center; (one point per way or relation), out geom; (full geometry), out count;. Limits on this instance: query timeout from the template option, 2 GB memory per query, no per-IP rate limit (all requests arrive from the tester).

Full reference: Overpass QL, language guide, Overpass documentation. Try queries interactively with overpass turbo after setting its server to this instance.

curl -s -X POST /api/overpass/api/interpreter \
  --data-urlencode 'data=[out:json][timeout:25];
    node(around:500,52.5219,13.4132)[amenity=cafe];
    out;'
const ql = `[out:json][timeout:25];nwr(around:150,${lat},${lon})[name];out tags center 40;`;
const r = await fetch("/api/overpass/api/interpreter", {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({ data: ql }),
});
const { elements, osm3s } = await r.json();   // elements[].tags, osm3s.timestamp_osm_base
area[...] filters (for example area[name="Berlin"]) only work when the template option "Area queries" is switched on. It is off by default because building the areas blocks the database while it writes. around, bbox and id queries always work. Errors come back as an HTML page with status 200, so parse the response as JSON only when it starts with {.

Data timestamp and provenance

All four services run on OpenStreetMap data (ODbL, © OpenStreetMap contributors): tiles from the Protomaps planet build, routing, geocoding and Overpass from Geofabrik extracts. The data timestamp is reported by /api/nominatim/status, /api/routing/status and osm3s.timestamp_osm_base in every Overpass answer.