Using occurrence API in GIS systems: GeoJSON format

To get started with the API you can also read:

• General info and access_token
• Using occurrences API
• In Finnish: Adding API links to QGIS

General information about the GeoJSON standard:

• https://geojson.org/
• Try it on map: https://geojson.io
• Create a web page with maps: https://leafletjs.com/examples/geojson/ or https://openlayers.org/en/latest/examples/geojson.html

Browsing occurrences as a list

You can generate a link to FinBIF API and add the link as a layer to your GIS system. There are four things you need to define:

• Filters - how do you want to narrow your search
• Page size and page number - to deal with a large amount of features
• What kind of features you want
• What other data you want to be included about the occurrence (species name, date, data source, coordinate accuracy, ...)

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 divide the results to multiple layers

?pageSize=10000&page=1 ?pageSize=10000&page=2 ?pageSize=10000&page=3 ...

Feature type

You can use this parameter to define what kind of features the GeoJSON response will contain. The coordinate reference system is always WGS84 by default.

• featureType
  • CENTER_POINT - Center point of the occurrence area; you can include coordinate accuracy in meters to selected fields
  • ENVELOPE - Envelope or bounding box of the occurrence area
  • ORIGINAL_FEATURE - Point, line, polygon of the original occurrence - in case the occurrence has multiple different features this API returns the envelope of the occurrence features, because most GIS systems do not support multiple features

Selected fields

Each occurrence will be one feature in the response. Each feature has a properties -object that will contain the defined data 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

As a final thing you must include a format=geojson parameter OR Accept: application/geo+json header to the API link

https://api.laji.fi/v0/warehouse/query/unit/list?format=GeoJSON&featureType=ORIGINAL_FEATURE&crs=WGS84&pageSize=10&page=1&selected=unit.taxonVerbatim,unit.linkings.taxon.scientificName,gathering.eventDate,gathering.interpretations.coordinateAccuracy

Sum/aggregate queries

In addition to browsing occurrences as a list our API allows to do queries that group occurrences together along one or few selected fields. This can for example be used to generate heat maps (aggregate by a 10km x10km box) that visualize amount of occurrences, age of occurrences etc.

https://api.laji.fi/v0/warehouse/query/unit/aggregate?

This is accomplished using the above endpoint. It has the same format, crs and featureType parameters as the /list query.

It is possible to define a custom grouping. To do this, leave crs and featureType parameters empty. Add two or four coordinate fields as aggregateBy parameter. This example groups occurrences to half degree boxes:

https://api.laji.fi/v0/warehouse/query/unit/aggregate?format=geojson&aggregateBy=gathering.conversions.wgs84Grid05.lat,gathering.conversions.wgs84Grid05.lon