The Knowledge Centre for Biodiversity (KCBD) Global Biodiversity Data Services (GBDS) - formerly the Digital Observatory for Protected Areas (DOPA) - processes open-access global reference datasets to generate harmonised metrics and indicators on biodiversity and its associated pressures. These outputs are distributed through the GBD web services, which support a range of web applications, including the Query Builder and Swagger UI. 

This document presents a practical guide on how to use the Query Builder and Swagger UI front-end tools, tailored to different user profiles.

For a full description of the GBDS data distribution architecture, see the technical report: JRC Global Biodiversity Data Services (GBDS): Data Distribution Architecture, REST API and Query Builder.

Disclaimer

Use of the GBD web services requires full understanding and acceptance of the following terms: 

• The GBD web services provide metrics and indicators calculated using datasets from third-party sources. The original datasets are not distributed through the GBD web services and remain available from their respective providers. 

• Use of the data may be restricted for commercial purposes. 

• Proper citation of sources is required when using the data. 

• Users are encouraged to consult the authoritative reference sources before applying the data. 

• Frequent users of the services are encouraged to inform the JRC of their activities. 

• Accessing and using data via Query Builder or REST API implies explicit acceptance of these terms. 

Query Builder

Query Builder’s main purpose is to list and describe functions available in the GBDS, providing access to the wide range of biodiversity metrics and indicators precomputed by the KCBD. A non-exhaustive list of features offered by Query Builder is the following: 

• List available GBD versions and functions 

• Filter available functions 

• Retrieve a detailed list of a function’s sources 

• Filter output parameters (indicators) and reduce the volume of output 

• Filter input parameters 

• Navigate the results withing the interface 

• Extract results as CSV, HTML 

• Generate URL for the specific combination 

   

Step 1: Accessing the Query Builder via the EU Login account

Access to the Query Builder requires an EU account, the EU Login.

For users who do not yet have an account, register at: https://webgate.ec.europa.eu/cas/eim/external/register.cgi

You will further need to request access to the Query Builder to ensure end-users are agreeing with the various underlying data licenses. 

Step 2: Requesting access to the Query Builder

Follow this step if you are not an already registered user:

1. Log in with your EU Login credentials and navigate to: https://dopa.jrc.ec.europa.eu/restapi/ui/welcome

2. Select the “REGISTER” option (Fig. 1, point 1). A pop-up form will appear.

3. Enter a short description of your intended use and the name of the organisation, institution, or other entity with which you are affiliated (Fig. 1, point 2). The “SUBMIT” button (Fig. 1, point 3) activates once this field is filled.

4. Submit the form. If your request is approved, you will receive an automated confirmation email from the KCBD functional mailbox. If needed, the KCBD team will contact you directly.

Once your registration has been approved, you can access the Query Builder by clicking the “PROCEED TO QUERY BUILDER” button.

Step 3. Selecting a data version

Once logged in, select the version of the GBD you want to work with (Fig. 2, point 1). The latest stable version is preselected by default. Available functions will load on screen, displayed in green (Fig. 2, point 2). 

`

Note that there is a fair usage rate limit on a per minute basis. If the user makes excessive requests, then no results will be delivered. You can request a higher rate limit through the KCBD functional mailbox (EC-biodiversity-KC@ec.europa.eu). The authentication can happen with EU Login for web browser navigation or with API key for programmatic access. 

Step 4. Filtering functions

Use the filter bar to narrow down the list of available functions (Fig. 7, point 1). You can filter based on:

• Report level (Fig. 3, point 2): filter by the geographic or administrative level at which metrics are calculated (e.g., country, protected area).

• Function theme (Fig. 3, point 3): filter by thematic category (e.g., species, land degradation). 

• Data sources (Fig. 3, point 4): filter by the underlying global datasets used to compute the indicators. 

• Function’s name (Fig. 3 point 5): search for a specific function by name. 

You can select the available pills for each category (green outline on grey background) and apply immediately that filtering option (Fig. 3). 

Click on a function’s name (Fig. 3, point 6) to load its details.

Step 5. Exploring a function and retrieving data

After selecting the desired function, the page area is divided into four parts: 

1. Function details: description of the selected function and its original data sources (Fig. 4, point 1). 

2. Function output parameters: it is possible to reduce the function’s return data/columns by selecting which columns to include in the results (Fig. 4, points 2 and 3). 

3. Function input parameters: it is possible to filter the return data based on the predefined parameters (Fig. 4, points 4 and 5). The most common parameter is the country code, which limits the return data to the selected country. A helper pop-up (Fig. 4, point 6) provides a reference table of country names with their ISO 2 and 3 codes. 

   Output and input function parameters might be an extensive list - in that case, the “filter on name” search bar feature might be helpful (Fig. 4, points 3 and 4). 

   

4. Function testing: the information of input and output parameters is formatted as a URL and displayed in the appropriate field, as shown in Figure 5.

   

   Click “TEST” (Fig. 6, point 1) to load the function directly into the page, i.e. to display the return data directly on the page. Use the copy URL button (Fig. 6, point 2) to copy the request URL to your clipboard. The URL is displayed on screen (Fig. 6, point 3) for debugging purposes. Different formats are available for data download - select your preferred output format from the dropdown menu (Fig. 6, point 4). The available data returned by the function is displayed below the controls described above (Fig. 6, point 5).

   

Swagger UI

The Swagger UI offers a familiar way to programmers and technical users to list and experiment with the GBD REST API. Below (Fig. 7) is a typical screenshot from the Swagger interface. 

As with the Query Builder interface, access to the data via Swagger UI requires an EU Login account and explicit user registration via the registration process – if necessary, follow Steps 1 and 2 described in the Query Builder section above.

After registration approval, users can request programmatic access through API key by contacting the KCBD functional mailbox. The requested API key will be sent to them manually – this last step will be automated in the future.

The Swagger interface is auto generated from the OpenAPI specification served from the GBD REST API. Every version of GBD has its own OpenAPI specifications, as there might be changes between releases. OpenAPI specification is well-known among technical users and is self-descriptive.

Swagger interface provides basic functionality to execute REST API queries to the GBDS back end. It serves a fixed default version of the GBD. Users are generally advised to use the Query Builder, which allows better control and experimentation on the data actually available.