API.LAJI.FI
Documentation
Documentation about the API exists in two places:
- Our API provides OpenAPI Specification (also known as swagger). OpenAPI specification can be used in two ways:
- On the front page of the API you can read the specification in human readable format and try out making requests (you need an access token).
- The specification is available in machine readable format.
- These documentation pages you are reading provide additional information, explanations and examples.
Access token
Using our API requires an access token. We have several reasons for this:
- It allows us to monitor who is using our API
- In the future we may put performance limits for access tokens
- We can grant additional permissions to tokens
You can order your own access token by making a HTTP POST request to /api-users endpoint.. The body of the request should contain your email (Content-Type: application/json):
{ "email": "my.email@example.com" }
Access token will be sent to your email address. Each request you make to the API must have ?access_token=<token> parameter OR you can provide is as Authentication header value.
On the front page of the API, you can add your token to the top right corner and it will be added to every request.
Test service
Test/dev API has the same features as the production API but can have less data and some of it may be bogus test data. It is best to start with the test service and move on to the production service after your application is in stable state. Test API can be found from apitest.laji.fi.
Test service may have bugs and new features that are not yet in production or have not yet been noted in the change log.
Test service uses a different access token. You can order your token the same way as with the production API.
Endpoints
The following explains the purpose of the different endpoints provided by the API:
Occurrence data
- Warehouse - Data warehouse endpoint for querying occurrence data. Can be also used to send data to the data warehouse. Read more on Data warehouse API.
- Collection - Metadata about occurrence datasets/collections. All occurrences belong to one collection and the metadata provides information about the dataset. This endpoint also contains metadata of datasets that has not yet been shared to FinBIF as occurrence data (or they might not even be in digital format yet).
- Source - Data source. Each occurrence has a source. The source might be an IT-system, but also an Excel spreadsheet copied to FinBIF for long term storage, etc.
Taxonomy
- Taxa - Information about naming of organisms, classifying organisms in a hierarchical system or in taxonomic ranks, distribution data and biological interactions, identifiers across different systems, etc. Read more on Taxonomy API.
- InformalTaxonGroup - Informal groups may be taxonomic groups (such as Aves) or can be used to group similar species together (for example Aphyllophoroid fungi). Some species do not belong to any informal groups and some may belong to several. Informal groups can be used to filter taxa and occurrences. This endpoint provides a list and hierarchy of the groups.
- Publication - Taxa can contain scientific citations to publications (for example source of name, source of status in Finland, etc). This endpoint provides information about the publications (name, link, doi, etc).
- Checklist - Taxa endpoint contains information about several different independent checklists. The most important checklist is the FinBIF master checklist that is used as the base for occurrence data and contains most information.
Other
- Metadata - Variable names, descriptions, ranges, enumeration values, etc in three languages. This data can be browsed on schema.laji.fi in human readable format.
- Area - Countries, Finnish municipalities, Finnish biogeographical provinces, etc.
- Person - Person name, friends, profile, settings, etc. The only information available to everyone is person ID and name. To access rest of the data, a personToken of a logged in user must be included to the request. Read more on User management.
Helpers
- APIUser - Request an access token.
- Autocomplete - Endpoint for implementing an autocomplete field. Can be used for taxa, collection metadata or friends (person).
- PersonToken - Information about a logged in user. Read more on User management.
Vihko form service
- Form - A form definition (name, description, fields, ...)
- Document - Insert, update or delete a document (using one of the forms).
- Image - Insert, update or delete occurrence, habitat, etc images that belong to some document.
Laji.fi portal helpers
- Feedback - API for the feedback form.
- Information - Contents of these information pages.
- Logger - Logs JavaScript errors.
- News - The news visible on the portal.
Additional notes
Use the API through https so that you do not reveal your access token to outsiders. (Http request will be redirected to https, but the first request will still be unsecured).
About difference between PersonToken and access_token parameters: Some endpoints require a personToken parameter. These endpoints provide information about a logged in user or execute the request with that user's permissions. The PersonToken is the identify of the user doing the request. Access_token is included to all request and provides information about the IT system doing the request and it's permissions. For /warehouse endpoints there is also permissionToken. Permission token (also called API Key) is gained via a data request or ordering one via Public authorities portal. Permission token grants access to secured/private data, using the filters defined when acquiring the token.