API-Leitfaden (v1)

Versionierte, öffentliche API. Referenz: ADR-0019. Interaktiv ausprobieren: /docs/api. Maschinenlesbar: GET /api/v1/openapi.json.

Basis

https://landnutzen.vercel.app/api/v1

Pfad-versioniert (/api/v1). Breaking Changes → /api/v2; neue Felder werden additiv innerhalb v1 ergänzt (Contract bleibt stabil).

Authentifizierung

Zweistufig — die API funktioniert ohne Key:

Modus	Wie	Limit
Anonym	kein Header	IP-Tageslimit (Mass-Scraping-Schutz)
API-Key	`Authorization: Bearer ln_…` oder `X-API-Key: ln_…`	eigenes, höheres Tageslimit + Audit

Gespeichert wird nur ein SHA-256-Hash des Keys, nie der Klartext. Ungültiger/widerrufener Key → 401. Key-Ausstellung erfolgt aktuell durch die Plattform (Self-Service folgt mit dem Admin-Dashboard).

Endpunkte

`GET /api/v1/report`

Parameter	Ort	Pflicht	Beispiel
`address`	Query	ja	`Rathausplatz 1, 2230 Gänserndorf`

curl "https://landnutzen.vercel.app/api/v1/report?address=Rathausplatz%201%2C%202230%20Gänserndorf"

`POST /api/v1/report`

curl -X POST https://landnutzen.vercel.app/api/v1/report \
  -H "Content-Type: application/json" \
  -d '{"address":"Rathausplatz 1, 2230 Gänserndorf"}'

Erfolg (200) = Report-JSON nach Report-Contract — kein Wrapper. Antwort- Header: X-RateLimit-Limit, X-RateLimit-Remaining, X-Auth-Mode.

Fehler-Envelope

Stabil bei jedem Nicht-2xx:

{ "error": { "code": "address_missing", "message": "…" } }

Status	code	Bedeutung
`400`	`address_missing` / `invalid_json`	Eingabe fehlt/ungültig
`401`	`unauthorized`	API-Key ungültig oder widerrufen
`429`	`rate_limited`	Tageslimit erreicht (`Retry-After`)
`500`	`internal`	unerwarteter Fehler

Ehrliche Datenlage

Nicht verfügbare oder unsichere Datenschichten stehen in jedem Report unter meta.degraded (Layer, Grund, Fallback). Die Widmung ist eine Indikation (nicht rechtsverbindlich), Kostenrahmen sind Grob-Schätzungen. Quellen/Lizenzen je Report unter sources — siehe Datenquellen & Lizenzen.