Erste Schritte

Erfahren Sie, wie Sie API v2 für Schutzgebietsdaten-Workflows integrieren.

Dieser Leitfaden hilft Ihnen, den Hauptanwendungsfall der Digitize API umzusetzen: das Importieren von Schutzgebieten und deren fortlaufende Aktualisierung.

Erstimport relevanter Schutzgebiete

Zum Einstieg können Sie die Liste der Schutzgebiete abrufen. Wenn Sie den vollständigen Datensatz nutzen möchten, erreichen Sie ihn über:

GET /api/v2/protected-areas

Dieser Endpoint liefert eine Standardmenge an Feldern und paginierte Daten. Falls diese Antwort bereits alle benötigten Informationen enthält, sind Sie startklar. Wenn Sie mehr Details benötigen, haben Sie zwei Möglichkeiten:

  1. Erweitern Sie die Antwort über den Parameter 'fields'. Siehe unsere interaktive Dokumentation für weitere Informationen.
  2. Reduzieren Sie die Erstabfrage auf die UUIDs (mit 'fields=uuid') und rufen Sie anschließend die vollständigen Details über den einzelnen Endpoint ab: GET /api/v2/protected-areas/{uuid}
    Auch dieser Endpoint unterstützt den 'fields'-Parameter zur Anpassung der Antwort.

Wenn Sie nur einen bestimmten Teil der Daten benötigen, können Sie Filter verwenden – z. B. um nur Nationalparks in Deutschland abzurufen. Dazu benötigen Sie zuerst die relevanten IDs der Filter:

  1. Abruf der category_id für Nationalparks (z. B. 1): GET /api/v2/protected-area-categories
  2. Abruf der country_id für Deutschland (z. B. 1): GET /api/v2/countries
  3. Verwenden Sie beide Filter, um den gewünschten Datensatz zu erhalten: GET /api/v2/protected-areas?category_id=1&country_id=1

Prüfung auf neue, geänderte und gelöschte Gebiete

Neue und aktualisierte Daten

Um Ihre Daten aktuell zu halten, verwenden Sie den updated_after Parameter: GET /api/v2/protected-areas?updated_after=YYYY-MM-DD

Dies liefert nur Schutzgebiete, die seit dem angegebenen Datum aktualisiert wurden.

Dieser Parameter wird auch von den Endpoints für Tierarten und Organisationen unterstützt.

Gelöschte Daten

Um gelöschte Schutzgebiete nachzuverfolgen, nutzen Sie unseren speziellen Endpoint: GET /api/v2/protected-areas/deleted
Sie können nach einem bestimmten Datum filtern mit: GET /api/v2/protected-areas/deleted?date=YYYY-MM-DD (liefert gelöschte Schutzgebiete nach dem angegebenen Datum; verwenden Sie den Vortag, um auch Löschungen von diesem Datum einzuschließen).

Besonderheiten beim Sync von Sperrungen und Hinweisen

Für den Einstieg empfehlen wir, über GET /api/v2/closures-and-notices zunächst einmalig alle Datensätze abzurufen, die für Ihre Anwendung relevant sind. Über den Parameter fields können Sie gezielt steuern, welche Felder in der Antwort enthalten sind und so die Datenmenge reduzieren.

Der Listen-Endpunkt liefert standardmäßig aktuelle und bevorstehende Datensätze. Wenn Sie beim Erstimport auch bereits abgelaufene Datensätze übernehmen möchten, ergänzen Sie entsprechende Datums- oder Statusfilter.

GET /api/v2/closures-and-notices?fields=uuid,name,type,reason_id,start_on,end_on,daytime_start,daytime_end,activity_ids,source_id

Für spätere inkrementelle Aktualisierungen können Sie gezielt alle Datensätze abrufen, die seit Ihrem letzten erfolgreichen Sync geändert wurden. Nutzen Sie dafür den Parameter updated_after: GET /api/v2/closures-and-notices?updated_after=YYYY-MM-DD

Wenn Sie Datensätze lokal speichern, sollten Sie den Status — aktuell, bevorstehend oder abgelaufen — anhand von start_on, end_on, daytime_start und daytime_end selbst berechnen. Berücksichtigen Sie dabei die jeweils relevante lokale Datums- und Zeitlogik.

Wichtig:

Datensätze können auch dann ablaufen, wenn sie seit dem letzten Abruf nicht geändert wurden. Anwendungen, die für Aktualisierungen den Parameter updated_after verwenden, sollten deshalb lokal gespeicherte Datensätze regelmäßig anhand des aktuellen Datums und der aktuellen Uhrzeit neu bewerten.

Wenn Sie den Status nicht selbst berechnen möchten, können Sie serverseitige Filter wie active_on, status, die Datumsbereichsfilter starts_after, starts_before, ends_after und ends_before sowie bbox, type, source_id, source_kind, activity_id und reason_id verwenden.

Zusätzliche Hinweise

  • Benutzen Sie die Feldfilterung (z. B. ?fields=id,name,geometry um die Datenmenge zu verringern und die Performance zu verbessern.
  • Bitte beachten Sie das Fair-Use-Prinzip: Wir setzen keine festen Zugriffsbeschränkungen durch, bitten jedoch alle Nutzer*innen, Anfragen verantwortungsvoll zu stellen und übermäßige oder missbräuchliche Nutzung zu vermeiden.
  • Beobachten Sie unser Changelog, um Schemaänderungen und neue Versionen nicht zu verpassen.

Wenn Sie Fragen haben oder Unterstützung benötigen, kontaktieren Sie uns gerne jederzeit.