Getting Started

This guide helps you implement the primary use case of the Digitize API: importing data on protected areas and keeping it up to date.

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 /api/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 /api/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 /api/v2/protected-area-categories
2. Get the country_id for Germany (e.g., 1): GET /api/v2/countries
3. Use both filters to get the targeted dataset: GET /api/v2/protected-areas?category_id=1&country_id=1

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 /api/v2/protected-areas/deleted
You can filter by a specific date using: GET /api/v2/protected-areas/deleted?date=YYYY-MM-DD (returns deletions after the given date; use the previous day to include deletions from that date).

Closures & Notices sync specifics

For GET /api/v2/closures-and-notices, start with a one-time fetch of all records relevant to your application. Use the fields parameter to control which fields are included in the response and reduce payload size.

The list endpoint returns current and upcoming records by default. If your initial sync should also include expired records, add matching date or status filters.

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

For later incremental syncs, request records changed since your last successful sync. Use the updated_after parameter for this: GET /api/v2/closures-and-notices?updated_after=YYYY-MM-DD

If you store records locally, you should calculate the status, current, upcoming, or expired, yourself from start_on, end_on, daytime_start, and daytime_end. Respect the relevant local date and time handling.

Consumers that do not want to calculate state themselves can use server-side filters such as active_on, status, the date range filters starts_after, starts_before, ends_after, and ends_before, plus bbox, type, source_id, source_kind, activity_id, and reason_id.

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, feel free to contact us anytime.