Geo API für amtliche Geodaten

Maschinenlesbare OpenAPI-Spezifikation

Für SDK-Generatoren, API-Clients und KI-Agenten steht die Metadatenebene zusätzlich als OpenAPI 3.1 bereit. Das Dokument beschreibt Endpunkte, Parameter, Authentifizierung und Antwortschemata. Der Feature-Host bleibt bewusst dynamisch: Verwenden Sie immer die absolute features_url aus der Ticketantwort.

Grundlagen

Schnellstart

Die folgenden Aufrufe zeigen den vollständigen Ablauf: Katalog öffnen, eine WFS-Ebene finden, ein Ticket ausstellen und Features abrufen. Benötigt werden curl und jq.

1. 1. Bundesländer abrufen

   export KARTENWERK_API_KEY="ak_…"
   
   curl --fail --silent --show-error \
     -H "Authorization: Bearer $KARTENWERK_API_KEY" \
     "https://kartenwerk.co/api/v1/geo/regions?limit=16"

2. 2. WFS-Ebene suchen

   Das Beispiel sucht Flurstücksebenen in Nordrhein-Westfalen.

   curl --fail --silent --show-error \
     -H "Authorization: Bearer $KARTENWERK_API_KEY" \
     "https://kartenwerk.co/api/v1/geo/regions/DE-NW/layers?protocol=wfs&search=flurstueck&limit=20"

3. 3. Ticket ausstellen

   Eine Ebenen-ID hat die Form geo1.STATE.base64url(service_url).base64url(layer_name). Die beiden Base64url-Teile werden ohne Padding aus den unveränderten UTF-8-Werten der Katalogantwort gebildet. Für den Schnellstart verwenden wir die im vorherigen Schritt gesuchte NRW-Flurstücksebene.

   export LAYER_ID="geo1.DE-NW.aHR0cHM6Ly93d3cud2ZzLm5ydy5kZS9nZW9iYXNpcy93ZnNfbndfYWxraXNfYWFhLW1vZGVsbC1iYXNpZXJ0.YWR2OkFYX0ZsdXJzdHVlY2s"
   
   TICKET_RESPONSE=$(curl --fail --silent --show-error \
     --request POST \
     -H "Authorization: Bearer $KARTENWERK_API_KEY" \
     -H "Content-Type: application/json" \
     "https://kartenwerk.co/api/v1/geo/tickets" \
     --data "{"layer_ids":["$LAYER_ID"],"target_crs":"EPSG:25832"}")
   
   export TICKET=$(printf '%s' "$TICKET_RESPONSE" | jq -r '.token')
   export FEATURES_URL=$(printf '%s' "$TICKET_RESPONSE" | jq -r '.layers[0].features_url')

4. 4. Features abrufen

   Übernehmen Sie token und features_url aus der Ticketantwort. Das Ziel-CRS muss dem Ticket entsprechen; zu jeder Bounding Box gehört ein explizitesbbox_crs.

   curl --fail --silent --show-error \
     --request POST "$FEATURES_URL" \
     -H "Authorization: Bearer $TICKET" \
     -H "Content-Type: application/json" \
     --data '{
       "bbox": [356000, 5645000, 357000, 5646000],
       "bbox_crs": "EPSG:25832",
       "target_crs": "EPSG:25832",
       "limit": 1000
     }'

Endpunkte

Die vier Metadaten-Endpunkte verwenden den API-Key. Nur die letzte Feature-Abfrage verwendet das Ticket.

const base64url = (value) =>
  Buffer.from(value, "utf8").toString("base64url");

const layerId = ({ state, service_url, layer_name }) =>
  `geo1.${state}.${base64url(service_url)}.${base64url(layer_name)}`;

{
  "filter": {
    "property": "nutzung",
    "op": "in",
    "value": ["Wohnbaufläche", "Industrie- und Gewerbefläche"]
  },
  "target_crs": "EPSG:4326",
  "limit": 1000
}

Paging und Koordinatensysteme

Zulässige Eingabe- und Zielsysteme sind EPSG:4326, EPSG:25832 und EPSG:25833. Antworten in EPSG:4326 sind RFC-7946-konformes GeoJSON. Projizierte Antworten tragen zusätzlich ein GeoJSON-CRS-Mitglied, damit GIS-Software die Datei korrekt verortet.

Fehler, Warnungen und Lizenzen

{
  "schema_version": 1,
  "error": {
    "kind": "upstream_timeout",
    "message_de": "Der Landesdienst hat nicht rechtzeitig geantwortet.",
    "message_en": "The state service did not answer in time.",
    "http_status": 504,
    "upstream_status": null,
    "upstream_message": null,
    "retry_after_seconds": 30,
    "circuit": {
      "state": "half_open",
      "retry_at": "2026-08-08T10:15:00.000Z"
    },
    "request_id": "…"
  }
}