API-Dokumentation

Die LageLuchs-API liefert LuchsScore, Standortklasse (A–D), Trend und Dimensions-Scores je Region als JSON. Der Zugang erfordert einen API-Key aus deinem Konto (Developer-Abo).

Authentifizierung

Sende deinen API-Key bei jedem Request — als Bearer-Token oder im x-api-key-Header:

Authorization: Bearer ll_live_…
# oder alternativ:
x-api-key: ll_live_…

Endpunkte

GET/api/v1/regions

Paginierte Liste aller ~11.000 Regionen. Filtere nach Verwaltungsebene mit type.

type — gemeinde | landkreis | bundesland (optional)

page — Seitennummer, 1-basiert (Standard: 1)

per_page — Ergebnisse pro Seite, max. 500 (Standard: 100)

curl -H "Authorization: Bearer ll_live_…" \
  "https://lageluchs.de/api/v1/regions?type=landkreis&per_page=50"

{
  "data": [
    { "ags": "01001", "name": "Flensburg", "type": "landkreis", "slug": "flensburg" },
    { "ags": "01002", "name": "Kiel", "type": "landkreis", "slug": "kiel" }
  ],
  "meta": { "total": 400, "page": 1, "per_page": 50, "pages": 8 }
}

GET/api/v1/regions/search?q=

Suche nach Regionen per Name (min. 2 Zeichen). Gibt max. 10 Treffer zurück. Ideal für Discovery: erst suchen, dann AGS nehmen, dann Region abrufen.

q — Suchbegriff (Pflicht, min. 2 Zeichen)

curl -H "Authorization: Bearer ll_live_…" \
  "https://lageluchs.de/api/v1/regions/search?q=München"

{
  "data": [
    { "ags": "09162", "name": "München", "type": "landkreis", "slug": "muenchen" },
    { "ags": "09184", "name": "München (Landkreis)", "type": "landkreis", "slug": "muenchen-landkreis" }
  ]
}

GET/api/v1/regions/{ags-oder-slug}

Vollständige Score-Daten einer Region per AGS (8-stellig für Gemeinden, 5-stellig für Landkreise) oder URL-Slug.

curl -H "Authorization: Bearer ll_live_…" \
  https://lageluchs.de/api/v1/regions/05315000

{
  "ags": "05315000",
  "name": "Köln",
  "type": "landkreis",
  "slug": "koeln",
  "luchs_score": 61,
  "trend": "stable",
  "standortklasse": "B",
  "dimension_scores": {
    "bevoelkerung": 72,
    "wirtschaft": 65,
    "arbeitsmarkt": 58,
    "infrastruktur": 80,
    "immobilien": 43
  },
  "data_vintage": "2025-01-01",
  "trust_level": "hoch"
}

GET/api/v1/regions.csv

Alle Regionen als CSV-Download (AGS, Name, Typ, Slug). Kein Paging — geeignet für lokales Caching des AGS-Verzeichnisses, ohne Rate-Limits zu verbrauchen.

curl -H "Authorization: Bearer ll_live_…" \
  "https://lageluchs.de/api/v1/regions.csv" -o regionen.csv

ags,name,type,slug
01001,Flensburg,landkreis,flensburg
01002,Kiel,landkreis,kiel
01003,Lübeck,landkreis,luebeck
…

Rate-Limits

60 Anfragen pro Minute pro API-Key (gleitendes Fenster). Bei Überschreitung antwortet die API mit HTTP 429.

Response-Header: X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After

Fehlercodes

HTTP	code	Bedeutung
401	unauthorized	API-Key fehlt, ungültig oder widerrufen
403	forbidden	Kein aktives Developer-Abo
404	not_found	Region nicht gefunden (kein Score)
429	rate_limited	Rate-Limit überschritten
500	internal	Datenbankfehler

Alle Fehler verwenden dasselbe JSON-Format:

{ "error": { "code": "not_found", "message": "Region nicht gefunden." } }

OpenAPI-Spezifikation

Maschinenlesbare Spezifikation (OpenAPI 3.0) für Codegen und API-Clients: /api/v1/openapi.json