API Calls

API Documentation

The Protected Planet API is the official way of accessing data from the WDPA (World Database of Protected Areas), maintaned by the Protected Areas and Informatics programmes at UNEP-WCMC in Cambridge, UK.

Authentication

To make successful HTTP calls to the Protected Planet API, you must have a API token, obtainable through a simple request form.

Once received, you will need to append the token parameter to whichever set of parameters your API calls will contain. For brevity, the token parameter is omitted from the rest of this documentation, as it is always required. If an API call is executed with the token parameter missing or invalid, the server will respond with HTTP code 401 (Unauthorized) and an error message in a JSON object.

You can use the /test endpoint to check for the validity of your API token:

Countries

GET /v3/countries

Returns all countries, paginated. Accepts a with_geometry parameter, to
retrieve a geojson representation of the countries.

The accepted parameters are:

with_geometry (Boolean)
If set, returns the geojson representation of the geometry of the countries.
Defaults to false.
page (Number)
Controls the returned page. Defaults to 1.
per_page (Number)
Controls how many countries are returned per page. Defaults to 25.
For performance reasons, the maximum value is 50.

Protected Areas

GET /v3/protected_areas

Returns all protected areas, paginated. Accepts a with_geometry parameter, to
retrieve a geojson representation of the protected area.

The accepted parameters are:

with_geometry (Boolean)
If set, returns the geojson representation of the geometry of the protected areas.
Defaults to false.
page (Number)
Controls the returned page. Defaults to 1.
per_page (Number)
Controls how many protected areas are returned per page. Defaults to 25.
For performance reasons, the maximum value is 50.

GET /v3/protected_areas/search

Returns a collection of protected areas matching the given attributes. At the moment,
search is possible on the marine attribute and on the country ISO.

The accepted parameters are:

is_green_list (Boolean)
If set to true, returns all green listed protected areas, paginated.
If set to false, returns all non-green listed protected areas, paginated.
By default, this is unset: both green listed and non-green listed protected areas are returned.
marine (Boolean)
If set to true, returns all marine protected areas, paginated.
If set to false, returns all terrestrial protected areas, paginated.
By default, this is unset: both terrestrial and marine protected areas are returned.
country (String, 3 characters)
If set, returns all protected areas from the country with the given ISO3, paginated.
By default, this is unset: protected areas from all countries are returned.
designation (Integer)
If set, returns all protected areas designated with the given `id`, paginated.
By default, this is unset: protected areas with all designations are returned.
jurisdiction (Integer)
If set, returns all protected areas with the given jurisdiciton `id`, paginated.
By default, this is unset: protected areas with all jurisdictions are returned.
governance (Integer)
If set, returns all protected areas with the given governance `id`, paginated.
By default, this is unset: protected areas with all governances are returned.
iucn_category (Integer)
If set, returns all protected areas with the given IUCN category `id`, paginated.
By default, this is unset: protected areas with all IUCN categories are returned.
with_geometry (Boolean)
If set, returns the geojson representation of the geometry of the protected areas.
Defaults to false.
page (Number)
Controls the returned page. Defaults to 1.
per_page (Number)
Controls how many protected areas are returned per page. Defaults to 25.
For performance reasons, the maximum value is 50.