Integrating the FinBIF REST API with a Geographic Information Systems
The REST API of the Biodiversity Information Facility can be integrated into a GIS using query as a link, to which spatial definitions and API keys are added. Below are instructions on how to connect the interface to the QGIS software.
API Keys
There are two types of API keys: permissionToken and access_token.
- permissionToken: Available only from the authority portal or data request system. This key grants access to restricted data if you are entitled to such data. This key is search-specific, including search filters, so you do not need to define restrictions separately in the query.
- access_token: A personal key required for all API requests. If you do not have a key, you can order it to your email by following the instructions below.
Key for Restricted Data – permissionToken
Restricted data can only be accessed with an API key requested from the Authority Portal or the Data Request System.
If you want to obtain a permissionToken key, first perform your desired data search in the authority portal. The data must be limited by at least one search criterion, but there is no upper limit on the number of observations, as with observation downloads.
Next, click on Download Data and select Request API Key. You need to justify the use of the data in the same way as when downloading data. The API key is valid for either three months or one year from the date of the request, depending on your selection. If you need to use the data for longer, you must perform a new data search and request the key again.
After this, click Submit and copy your API key for safekeeping.
Personal access_token
You can order a personal access_token to your email via this link. Enter your email address in the format
my.email@example.com
in the white text box found behind the link and click Try it out. This way, you will receive your personal access_token key by email. More information in English can be found here.
Formatting GEOJSON query
A color-coded example query that explains the meanings of the different parts of an API link:
This example returns the original geometries of observations in the WGS84 coordinate system. If observations have been initially stored as different geometry types (points, areas, lines), the API will return three separate map layers. For example, if you want only centroids, replace ORIGINAL_FEATURE with CENTER_POINT. In this case, you will get only one map layer from the API.
Copy the example link containing the API key. Replace xxx with your API keys (permissionToken and access_token) and add pagination if necessary.
https://api.laji.fi/v0/warehouse/query/unit/list?format=GeoJSON&featureType=ORIGINAL_FEATURE&crs=WGS84&permissionToken=xxx&access_token=xxxAfter creating the API link according to your needs, you can copy it and use it to retrieve species observation data into any geographic information system or map service that supports reading GeoJSON format from an interface. Remember that the search you perform may contain restricted data, so you are responsible for using the API link according to the terms of use. Do not share your API keys or links containing them or the observation data retrieved from the API with anyone other than the relevant parties.
Note: If you do not have a permission_token, you can still use the API. In this case, you must define all restrictions directly in the query, and you will not have access to unrestricted observations. For example:
https://api.laji.fi/v0/warehouse/query/unit/list?format=GeoJSON&featureType=ORIGINAL_FEATURE&crs=WGS84&createdDateYear=2024&access_token=xxxUsing the REST API in QGIS
API users can create a query from the api.laji.fi interface and link the response to QGIS in GeoJSON format, allowing QGIS to fetch the map layer corresponding to the link into the map view.
Do not make corrections or other changes to observation data in geographic information systems. These corrections will not reach the Biodiversity Information Facility, so if you retrieve observations from there again, the changes will not be available. Corrections should be made locally to your data or using the quality control tool on Laji.fi.
Establishing an API Connection
In the QGIS project top menu, select Layer → Add Layer → Add Vector Layer.
In the window that opens, select Protocol/Protokolla: HTTPS, Cloud, etc.
Choose Type/Type as GeoJSON and add the API link to the URI address bar. Finally, click Add/Lisää.
An example of a URI address to use (add pagination if necessary, otherwise the API will return only the first 100 observations):
https://api.laji.fi/v0/warehouse/query/unit/list?format=GeoJSON&featureType=ORIGINAL_FEATURE&crs=WGS84&permissionToken=xxx&access_token=xxx
If observations have been initially stored as different geometry types (points, areas, lines), QGIS will fetch three separate map layers from the API. If you want, for example, centroids, replace ORIGINAL_FEATURE with CENTER_POINT. In this case, you will get only one map layer from the API.
Once the data has been loaded, you can save it in the usual way as part of your QGIS project, allowing the map layer fetched through the API to be updated each time QGIS is started. The API connection can also be refreshed with the F5 key. If necessary, you can make a local copy of the data on your computer by right-clicking the layer and selecting Export → Save Features As…, and changing the file format to, for example, Shapefile or GeoPackage.