Obtaining and using a permission token API-key
FinBIF occurrence data warehouse has two sides: public and private. Some occurrences are coarsened on the public side. It is possible to gain access to the private (full) data via a data request and in Public Authority Portal (PAP).
When making a data request and in PAP it is possible to order an API-key that provides access to the set of occurrences defined by the filters.
Use the granted/ordered API-key
https://api.laji.fi/v0/warehouse/query/unit/list?permissionToken=xxx&access_token=xxx
- permissionToken is received via granted data request or via Public Authority Portal - it is a secret that allows access to the private data
- access_token is the "normal" access token you need to use any features of the FinBIF API. Read more: https://laji.fi/about/3120
To get started with the API you can read the following
- General info and access_token
- Using occurrences API
- Occurrences in GIS format
- Permission token can also be used with our R-package
Example query
This example tells how to browse occurrences as a list. In addition to this you can use the API to get all data of single document and do aggregate (sum/group by) queries.
For the list query, there are the following things you can define
- Filters - how do you want to narrow your search
- Page size and page number - to deal with a large amount of occurrences
- What data fields you want to be included
Filters
You can use our portal to find out what possibilities there are to filter occurrences: https://laji.fi/observation . You can also browse our API documentation to read about all the possibilities (some are not present in the portal user interface)
Paging
Parameters pageSize and page define how many occurrences you will have on your layer and if there are more than the maximum 10.000, then you need to fetch the result in multiple pages
?pageSize=10000&page=1 ?pageSize=10000&page=2 ?pageSize=10000&page=3 ...
Selected fields
If no selected fields are defined, we have selected some default fields, but there are many more you can choose from. Read here about different fields: https://laji.fi/about/1400
Full list of fields is defined in the API documentation.
Example
https://api.laji.fi/v0/warehouse/query/unit/list?pageSize=10&page=1&selected=unit.taxonVerbatim,unit.linkings.taxon.scientificName,gathering.eventDate&time=2000/&target=Linnut,Nisäkkäät&access_token=xxx
In the above example, selected -parameter defines the selected fields, and time and target are filters.