Dokumentation.
Alles, was Sie für den ersten Aufruf und den Betrieb brauchen. Eine REST-API mit JSON, ein Schlüssel, zehn Endpunkte.
Schnellstart
- Legen Sie ein kostenloses Konto an und erstellen Sie dort einen Schlüssel. Der Free-Tarif enthält 1.000 Einheiten im Monat.
- Legen Sie ihn als Umgebungsvariable
FLURSTEIN_KEYab. - Fragen Sie den Grundstücksbericht für einen Punkt ab, zum Beispiel in Köln-Ehrenfeld.
curl "https://api.flurstein.de/v1/sites?lat=50.9497&lon=6.9183" \
-H "Authorization: Bearer $FLURSTEIN_KEY"import os, requests
r = requests.get(
"https://api.flurstein.de/v1/sites",
params={"lat": 50.9497, "lon": 6.9183},
headers={"Authorization": f"Bearer {os.environ['FLURSTEIN_KEY']}"},
)
site = r.json()
print(site["parcel"]["id"], site["parcel"]["area_official_m2"])const res = await fetch(
"https://api.flurstein.de/v1/sites?lat=50.9497&lon=6.9183",
{ headers: { Authorization: `Bearer ${process.env.FLURSTEIN_KEY}` } },
);
const site = await res.json();
console.log(site.parcel.id, site.constraints.length);Authentifizierung
Jede Anfrage trägt Ihren Schlüssel im Header Authorization:
Authorization: Bearer live_...Schlüssel beginnen mit live_ für den Betrieb oder test_ für Entwicklung und Tests. Sie sehen einen Schlüssel nur einmal, beim Anlegen. Wir speichern ihn nur als Hash. Im Dashboard können Sie Schlüssel anlegen, umbenennen und widerrufen.
Basis-URL für alle Endpunkte: https://api.flurstein.de/v1
Endpunkte
Alle Pfade relativ zur Basis-URL. Die Spalte rechts zeigt, wie viele Einheiten ein erfolgreicher Aufruf kostet.
| Methode und Pfad | Liefert | Einheiten |
|---|---|---|
GET /sites/{flurstueck_id}GET /sites?lat=&lon=GET /sites?address= | Der Grundstücksbericht: Flurstück, Adresse, Gemeinde, Gebäude, Nutzung und alle Schutzgebiete mit Überschneidungsfläche, Quellen und Namensnennung. | 3 |
GET /parcels/{id} | Ein Flurstück nach Flurstückskennzeichen: Gemarkung, Flur, Nummer, amtliche und berechnete Fläche, Adresse, Umring, Punkt im Flurstück. | 1 |
GET /parcels?lat=&lon= | Das Flurstück an einem Punkt. | 1 |
GET /parcels?address= | Flurstücke zu einer Adresse, wo das Land Adressen veröffentlicht. | 1 |
POST /parcels/search | Flurstücke in einem Rechteck oder Polygon, seitenweise (bis 100 je Seite, bis 1 km² je Anfrage). | 1 je Seite |
GET /parcels/{id}/buildings | Gebäude auf einem Flurstück: Funktion, Geschosse (wo vorhanden), Grundfläche, Anteil auf dem Flurstück. | 1 |
GET /land-use?lat=&lon= | Tatsächliche Nutzung an einem Punkt: einheitliche Klasse und die Klasse des Landes. | 1 |
POST /constraints | Hochwasser, Wasserschutz und Naturschutz für einen Punkt oder ein Polygon, mit Überschneidungsfläche. | 2 |
GET /communes/{ags} | Gemeinde nach Amtlichem Gemeindeschlüssel: Name, Kreis, Land, Umring (optional). | 1 |
GET /coverage | Abdeckung je Land und Ebene, Stand und Lizenz. Ohne Schlüssel. | kostenlos |
Gemeinsame Parameter
Gelten für jeden Endpunkt, der Geometrien oder Listen liefert.
| Parameter | Werte | Wirkung |
|---|---|---|
crs | 4326 (Standard) oder 25832 | Koordinatensystem der Geometrien: WGS84 in Grad oder UTM Zone 32 in Metern. Gilt auch für lat und lon in der Anfrage. |
geometry | true (Standard) oder false | Mit false ohne Umringe: kleinere Antworten, schnellere Suche. |
page_size | 1 bis 100 | Treffer je Seite bei der Suche. |
page | Token aus der vorigen Antwort | Die nächste Seite einer Suche. Jede Seite kostet 1 Einheit. |
Antworten und Statuscodes
Antworten sind JSON, Geometrien GeoJSON. Jede Antwort nennt das Release, jeder Datensatz seine Quelle. Fehler kommen als Problem Details nach RFC 9457.
| Status | Bedeutung | Kosten |
|---|---|---|
200 | OK | Einheiten laut Endpunkt |
304 | Unverändert seit Ihrem ETag | kostenlos |
400 | Anfrage ungültig, etwa ein Polygon über 1 km² | kostenlos |
401 | Schlüssel fehlt oder ist ungültig | kostenlos |
404 | Kein Flurstück an diesem Punkt, unter diesem Kennzeichen oder dieser Adresse | kostenlos |
429 | Kontingent aufgebraucht oder zu viele Abfragen pro Sekunde | kostenlos |
5xx | Fehler bei uns | kostenlos |
404 Not Found{
"type": "https://flurstein.de/fehler/address-not-found",
"title": "Adresse nicht gefunden",
"status": 404,
"detail": "Zu \"Musterstraße 99, 50823 Köln\" gibt es kein Flurstück mit dieser Adresse. Nordrhein-Westfalen veröffentlicht Adressen an Flurstücken und Gebäuden."
}Limits
Jeder Tarif hat ein Kontingent an Einheiten im Monat und eine Grenze an Abfragen pro Sekunde, siehe Preise. Beides gilt für Ihr Konto, über alle Schlüssel zusammen. Jede Antwort mit Schlüssel trägt die Header RateLimit-Limit (Einheiten im Monat), RateLimit-Remaining (davon noch frei) und RateLimit-Reset (Sekunden bis zum nächsten Monat, UTC).
Die Grenze pro Sekunde messen wir über zehn Sekunden: kurze Spitzen sind in Ordnung, solange der Schnitt passt. Darüber antwortet die API mit 429 und Retry-After: 10.
Ist das Kontingent aufgebraucht, antwortet die API mit 429, bis der nächste Monat beginnt oder Sie Mehrverbrauch freischalten. Mit Mehrverbrauch geht es weiter bis zu Ihrem Ausgabenlimit. Ihren Verbrauch je Tag sehen Sie im Dashboard.
Daten ändern sich nur mit einem neuen Release. Speichern Sie Antworten ruhig zwischen, und fragen Sie mit If-None-Match nach: unveränderte Daten antworten mit 304 und kosten nichts.
Namensnennung
Die meisten Länder verlangen, dass Sie die Quelle nennen, wenn Sie ihre Daten zeigen oder weitergeben. Jede Antwort enthält dafür das Feld attribution mit den fertigen Texten für genau die Daten in dieser Antwort.
Zeigen Sie diese Texte dort, wo Sie die Daten zeigen, etwa unter einer Karte oder im Impressum Ihrer Anwendung. Alle Quellen und Lizenzen stehen unter Quellen und Lizenzen.
Flurstein-Daten sind kein amtlicher Auszug aus dem Liegenschaftskataster. Bitte stellen Sie sie Ihren Nutzern auch nicht so dar.