Getting Started & Migration Guide

This guide helps you implement the primary use case of the DigitizeThePlanet API: importing data on protected areas and keeping it up to date. It also explains how to migrate from API version 1 to version 2.

Main Use Case

1. Initial import of relevant protected areas

To get started, fetch the list of protected areas. If you want to use our full dataset, you can retrieve it via:

GET /v2/protected-areas/

This endpoint returns a default set of fields and paginated data. If this default response includes everything you need, you're all set. If you require more details, you have two options:

  1. Extend the response via the 'fields' parameter. See the interactive documentation for more information.
  2. Reduce the initial request to only fetch UUIDs (using 'fields=uuid'), and then retrieve full details using the individual endpoint: GET /v2/protected-areas/{uuid}
    This endpoint also supports the 'fields' parameter for customizing the response.

If you only need a specific subset of data, you can apply filters — for example, to retrieve only national parks in Germany. To do this, first fetch the relevant filter IDs:

  1. Get the category_id for National Parks (e.g., 1): GET /v2/categories/
  2. Get the country_id for Germany (e.g., 1): GET /v2/countries/
  3. Use both filters to get the targeted dataset: GET /v2/protected-areas?category_id=1&country_id=1

Migration from v1:

All former protected area endpoints (e.g. protectedarea, protectedareabywdpa) are now consolidated into the main protected-areas endpoint with filtering options:

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

2. Update check for new, changed, and deleted areas

New and updated data

To keep your data current, use the 'updated_after' parameter: GET /api/v2/protected-areas?updated_after=YYYY-MM-DD

This will return only the areas that have been updated since the given date.

This parameter is also supported on endpoints for wildlife and organization data.

Deleted data

To track deletions, use our dedicated endpoint: GET /protected-areas/deleted/
You can filter by a specific date or relative number of days using: GET /protected-areas/deleted?date=YYYY-MM-DD or GET /protected-areas/deleted?days=1 (returns all deletions from the last day).

Migration from v1:

  • GET /api/protectedareabydate/YYYY-MM-DD → GET /api/v2/protected-areas?updated_after=YYYY-MM-DD
  • If running updates weekly, you can use: GET /api/v2/protected-areas?days=7

Additional Tips

  • Use field filtering (e.g., '?fields=id,name,geometry') to reduce payloads and improve performance.
  • Be mindful of fair use: While we do not enforce strict rate limits, we ask all users to make requests responsibly and avoid excessive or abusive usage.
  • Subscribe to our changelog for schema changes and version updates.

If you have questions or need support during migration, feel free to contact us anytime.