Limits und Zugang

Die Übersichten, das LoD2-GeoJSON und die Tilesets bleiben ohne Registrierung benutzbar. Der erste Call soll funktionieren, bevor du irgendwo eine Adresse einträgst. Ab einer bestimmten Menge wollen wir aber wissen, wer da ruft — nicht um zu bremsen, sondern um dich erreichen zu können, wenn ein Snapshot wechselt oder ein Endpoint sich ändert.

Der Trial-Key kostet nichts, braucht kein Konto und ist in einer Minute da. Er ist der Weg zu mehr als 1.000 Calls am Tag, schaltet für 7 Tage alle Pro-Endpoints frei und ist gleichzeitig der einzige Weg, dass wir dich bei Änderungen informieren können.

Welche Endpoints einen Key brauchen

Seit Oktober 2026 sind die eigentlichen Daten-Endpoints nach Tarif freigeschaltet (Tarife: lodapi.de/pricing). Übersichten und Listen bleiben frei.

Reihenfolge der Tarife: Free < Hobby < Pro < Business < Enterprise. Trial-Keys haben Pro-Umfang, kommen also 7 Tage lang an alle Endpoints der Tabelle.

Ohne Key auf einem gesperrten Endpoint kommt 401, mit einem Key unter dem Mindest-Tarif 403, beides als application/problem+json:

{
  "type": "https://lodapi.de/errors/api-key-required",
  "title": "Für diesen Endpoint brauchst du einen API-Key",
  "status": 401,
  "detail": "Dieser Endpoint ist ab Tarif Hobby freigeschaltet und braucht einen API-Key im Header X-API-Key. Einen Testkey bekommst du in einer Minute unter https://lodapi.de/key (7 Tage Pro-Umfang, ohne Registrierung).",
  "instance": "/v1/terrain/elevation",
  "required_tier": "hobby",
  "key_url": "https://lodapi.de/key"
}

{
  "type": "https://lodapi.de/errors/tier-insufficient",
  "title": "Dein Tarif reicht für diesen Endpoint nicht",
  "status": 403,
  "detail": "Dieser Endpoint braucht mindestens Tarif Pro; dein Key hat Tarif Hobby. Tarife und Upgrade: https://lodapi.de/pricing",
  "instance": "/v1/buildings/DESHPDHK0001gXAH/roof",
  "required_tier": "pro",
  "key_tier": "hobby",
  "pricing_url": "https://lodapi.de/pricing"
}

Im Python-SDK wird 401 zu AuthError, 403 zu ApiError mit status == 403; in beiden steht der detail-Text in exc.detail. Gesperrte Requests ohne Key zählen weiter gegen das Keyless-Tageslimit.

3D-Tiles sind nicht gesperrt. Die Kachel-Dateien (LoD2-3D-Tiles, Terrain-Mesh, Bodenbedeckung, Terrain-COGs) liefert tiles.lodapi.de statisch aus, ohne Key-Prüfung. Die Sperre betrifft nur die API-Endpoints oben.

Ohne Key: 1.000 pro Tag und IP

Jede Antwort auf einen keyless Request trägt das Rest-Budget im Header:

curl -si "https://api.lodapi.de/v1/buildings?bbox=8.68,50.11,8.69,50.12" | grep -i x-keyless
# X-Keyless-Remaining: 987

Batch-Skripte sollten den Header lesen und rechtzeitig auf einen Key umschalten, statt in die 429 zu laufen.

Was zählt: alle /v1/-Endpoints — Buildings, Tilesets, Terrain, Terrain-Mesh, OSM-Cover, Vegetation. Auch Fehlerantworten (404, 422) zählen, weil das Limit vor dem Handler greift.

Was nicht zählt:

• GET /v1/datasets und GET /v1/attribution — Coverage-Discovery und Lizenz-Pflichtangaben müssen immer erreichbar sein. Die Attribution ist Compliance-relevant: an eine Quellenangabe kommst du auch dann, wenn dein Budget aufgebraucht ist.
• POST /v1/keys/trial und GET /v1/keys/trial/{key} — der Weg zum Key darf nie vom Limit blockiert sein. Der Mint hat ein eigenes Limit (einige Keys pro IP pro Tag).
• Tiles auf tiles.lodapi.de (3D-Tiles, Terrain-COGs, GLB-Kacheln). Die kommen statisch vom Webserver, nicht aus der API, und sind vom Tageslimit nicht betroffen. Ein Cesium-Viewer läuft also nicht durch bloßes Herumfliegen ins Limit.
• /healthz, /openapi.json, /docs.

Die 429

Ist das Budget aufgebraucht, antwortet die API mit 429 Too Many Requests als application/problem+json (RFC 7807):

{
  "type": "https://lodapi.de/errors/keyless-daily-limit",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Ohne API-Key sind 1.000 Requests pro Tag und IP frei. Einen Testkey mit 5.000/Tag gibt es in einer Minute unter https://lodapi.de/key.",
  "instance": "/v1/terrain/elevation",
  "limit": 1000,
  "retry_after": 42317,
  "key_url": "https://lodapi.de/key",
  "docs_url": "https://lodapi.de/docs/guides/rate-limits"
}

Dazu die Header Retry-After (Sekunden bis zum Reset um Mitternacht UTC) und X-Keyless-Remaining: 0.

Am type erkennst du das Keyless-Limit eindeutig — der 429 vom Trial-Mint (zu viele Keys von einer IP) hat einen anderen type.

import httpx

r = httpx.get("https://api.lodapi.de/v1/buildings", params={"bbox": "8.68,50.11,8.69,50.12"})
if r.status_code == 429:
    problem = r.json()
    if problem["type"].endswith("/keyless-daily-limit"):
        raise SystemExit(f"Key holen: {problem['key_url']}")
    # sonst: Retry-After abwarten

Mit Key

Ein Key reist im Header X-API-Key mit:

curl -H "X-API-Key: lod_…" \
  "https://api.lodapi.de/v1/buildings?bbox=8.68,50.11,8.69,50.12"

Keyed-Traffic ist vom Keyless-Tageslimit nicht betroffen — kein X-Keyless-Remaining, kein 429 daraus. Stattdessen antworten wir mit dem Verbrauch gegen dein Kontingent:

• X-Lodapi-Quota-Used — Calls im laufenden Monat
• X-Lodapi-Quota-Limit — dein Monatskontingent (fehlt bei unbegrenzten Verträgen)

Diese Quota ist heute weich: sie wird gezählt und angezeigt, aber nicht durchgesetzt. Wer regelmäßig darüber liegt, hört von uns — per Mail, nicht per 429.

Was tun bei mehr Bedarf

Trial reicht nicht? Schreib an hello@lodapi.de mit einem Satz zum Use-Case. Und falls du gerade ein ganzes Bundesland Gebäude für Gebäude über die Feature-API ziehst: sag Bescheid, dafür finden wir einen besseren Weg als 500.000 Einzelrequests.

Verwandte Seiten

• Trial-Key holen
• POST /v1/keys/trial
• Quickstart