Limits

Lodapi bleibt 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 — und gleichzeitig der einzige Weg, dass wir dich bei Änderungen informieren können.

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