Erste Schritte & Migrationsleitfaden

Dieser Leitfaden hilft Ihnen, den Hauptanwendungsfall der DigitizeThePlanet API umzusetzen: das Importieren von Schutzgebieten und deren fortlaufende Aktualisierung. Zudem wird erklärt, wie man von Version 1 auf Version 2 migriert.

Hauptanwendungsfall

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

Migration von v1:

Alle früheren Endpoints zu Schutzgebieten (z. B. protectedarea, protectedareabywdpa) wurden in einem Hauptendpoint zusammengeführt und können über Filter gesteuert werden:

  • GET /api/protectedarea/ → GET /api/v2/protected-areas/
  • GET /api/protectedareabywdpa/ → GET /api/v2/protected-areas?wdpa_id=12345

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

Neue und aktualisierte Daten

Um Ihre Daten aktuell zu halten, verwenden Sie den Parameter 'updated_after': 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 /protected-areas/deleted/
Sie können entweder nach einem konkreten Datum oder einer relativen Tagesanzahl filtern: GET /protected-areas/deleted?date=YYYY-MM-DD oder GET /protected-areas/deleted?days=1 (liefert alle gelöschten Schutzgebiete des letzten Tages).

Migration von v1:

  • GET /api/protectedareabydate/YYYY-MM-DD → GET /api/v2/protected-areas?updated_after=YYYY-MM-DD
  • Wenn Sie wöchentliche Updates durchführen, können Sie Folgendes verwenden: GET /api/v2/protected-areas?days=7

Zusätzliche Hinweise

  • Nutzen 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 bei der Migration benötigen, kontaktieren Sie uns gerne jederzeit.