pywdpa Python package

Overview

The pywdpa Python package is an interface to the World Database on Protected Areas (WDPA) hosted on the Protected Planet website at https://www.protectedplanet.net. The pywdpa package provides functions to download shapefiles of protected areas (PA) for any countries with an iso3 code using the Protected Planet API at https://api.protectedplanet.net. The pywdpa package translates some functions of the R package worldpa (https://github.com/FRBCesab/worldpa) in the Python language.

Terms and conditions

You must ensure that the following citation is always clearly reproduced in any publication or analysis involving the Protected Planet Materials in any derived form or format:

UNEP-WCMC and IUCN (YEAR) Protected Planet: The World Database on Protected Areas (WDPA). Cambridge, UK: UNEP-WCMC and IUCN. Available at: www.protectedplanet.net (dataset downloaded the YEAR/MONTH).

For further details on terms and conditions of the WDPA usage, please visit the page: https://www.protectedplanet.net/en/legal.

Prerequisites

Access to Protected Planet API

This package uses the Protected Planet API to access data on world protected areas. You must first have obtained a Personal API Token by filling in the form available at https://api.protectedplanet.net/request. Then you need to set an environment variable (we recommend using the name WDPA_KEY) using either the command os.environ["WDPA_KEY"]="your_token" or python-dotenv.

GDAL

GDAL must be installed on your system.

To install GDAL on Windows, use the OSGeo4W network installer. OSGeo4W is a binary distribution of a broad set of open source geospatial software for Windows environments (Windows 11 down to 7). Select Express Install and install GDAL. Several Gb of space will be needed on disk to install this programs. This will also install OSGeo4W Shell to execute command lines.

To install GDAL on other systems, use your package manager, for example apt for Debian/Ubuntu Linux distributions.

sudo apt update
sudo apt install gdal-bin libgdal-dev

After installing GDAL, you can test the installation by running gdalinfo --version in the command prompt or terminal, which should display the installed GDAL version.

Installation

The easiest way to install the pywdpa Python package is via pip in the OSGeo4W Shell for Windows or in a virtual environment for Linux.

For Linux, create and activate a virtual environment before install pywdpa with pip:

cd ~
# Create a directory for virtual environments
mkdir venvs
# Create the virtual environment with venv
python3 -m venv ~/venvs/venv-pywdpa
# Activate (start) the virtual environment
source ~/venvs/venv-pywdpa/bin/activate

Install Python dependencies and pywdpa in the OSGeo4W Shell or in the newly created virtual environment:

# Upgrade pip, setuptools, and wheel
python3 -m pip install --upgrade pip setuptools wheel
# Install numpy
python3 -m numpy
# Install gdal Python bindings (the correct version)
python3 -m pip install gdal==$(gdal-config --version)
# Install pywdpa. This will install all other dependencies
python3 -m pip install pywdpa

If you want to install the development version of pywdpa, replace the last line with:

python3 -m pip install https://github.com/ghislainv/pywdpa/archive/master.zip

To deactivate and delete the virtual environment:

deactivate
rm -R ~/venvs/venv-pywdpa # Just remove the repository

In case of problem while installing GDAL Python bindings, try the following command:

python3 -m pip install  --no-cache-dir --force-reinstall gdal==$(gdal-config --version)

Contributing

The pywdpa Python package is Open Source and released under the GNU GPL version 3 license. Anybody who is interested can contribute to the package development following our Community guidelines. Every contributor must agree to follow the project's Code of conduct.