Taxonomy API

Concepts / Data model

Checklist: Checklist has an identifier, a name and a root taxon. Generally one checklist provides a non-overlapping taxonomy tree of a certain taxonomic group (for example all Biota or just Aves, etc). The most important checklist is the FinBIF master checklist. The API provides other checklists (and linking between the checklists) as well.

Taxon: Taxon has a parent (except for the root taxon) and possibly children. They form a taxonomic tree. In FinBIF a taxon is a taxon concept. The identifier belongs to a concept. The name of the concept may change over time, but the taxonomic coverage of the concept should never change. If a taxon concept is for example spitted to several other taxa, new concepts are created (as child of the old concept) and the old concept remains as an aggregate or other group.

Hidden taxon: A taxon can be hidden in the tree. In this case, when browsing the tree, the (non-hidden) children of the hidden taxon are moved up in the tree. Taxa endpoints can be used in two modes: hidden taxa are shown or are not shown.

Finnish taxon: The taxonomy can be browsed in “only Finnish” mode or in a mode where all taxa are shown. FinBIF master checklist consists mainly of Finnish species, but includes a large number of non-Finnish taxa as well, which are needed for example when managing collections that contain specimen from outside Finland. The definition of Finnishness varies across different taxonomic groups. Taxon experts of each group decide what they want to include and what not.

Invasive alien species: A taxon is considered invasive if it is mentioned in one of the Administrative statuses (use /metadata endpoint to get a list) that are used to define invasive species. Some administrative statuses discuss Finnish national lists of species and then there are the EU directive species.

/taxa/search

Search taxa by name. Most of this information also applies to /autocomplete endpoint (when using field=taxon).

Match type: Each match has a match type: exact, partial or fuzzy. You can limit the search to include only certain types. Fuzzy matching is slower than the others. We use this endpoint usually so that we first do exact,partial query and if there are no matches, then do a fuzzy match query.

Name type: Each name that matches the search word has a name type. The name type tells what kind of name it is: a scientific name, a homotypic synonym, vernacular name, etc.

Here is a list of different name types:

You can exclude certain name types. For example when doing an observation reporting form taxon autocomplete field, it might be a good idea to exclude misapplied names, uncertain synonyms, etc.

/taxa

/taxa – information about all taxa that match the filters as flat structure
/taxa/{id} – information about a single taxon
/taxa/{id}/children|parents – browse taxonomy as a tree
/taxa/{id}/species – all “species level” taxa as a flat structure that can be found under a certain parent and match the filters
/species – all “species level” taxa as a flat structure that match the filters

Note: /species endpoints return taxa that have taxon rank species or bellow (subspecies, variety, form, …) and also few taxon ranks above species (aggregate, ..). To limit the list to just species you can add taxonRank=MX.species filter.

Aggregate queries

This section explains the syntax for making aggregate queries.

aggregateBy – field1,field2=alias;field3=alias2
aggregateOrderBy – not implemented right now; sorts each aggregate by count descending
aggregateSize – how many rows to include (no paging available)

When using aggregateBy parameter, the result will contain a normal /taxa or /species result and in addition a aggregations object. So it is possible to get a list and aggregate results for the defined filters with a single query. If you want to exclude normal results and just have the aggregations, set pageSize=0.

Filters

This section contains information about specific filters that need additional information about their syntax, etc to be useful.

adminStatusFilters – Filter by values of /metadata/ranges/MX.adminStatusEnum (schema)
informalGroupFilters – Filter by values of /informal-taxon-groups
redListEvaluationGroups – Filter by values of /red-list-evaluation-groups
invasiveSpeciesMainGroups – Filter by values of /metadata/properties/HBE.invasiveSpeciesMainGroups
redListStatusFilters – Filter by values of /metadata/ranges/MX.iucnStatuses (schema)
typesOfOccurrence(Not)Filters – Filter by values of /metadata/ranges/MX.typeOfOccurrenceEnum (schema)
primaryHabitat – Syntax example: MKV.habitatM[MKV.habitatSpecificTypeJ] – Filter by primary habitat define for the taxon. First part of the syntax is the habitat. Habitats form a hierarchy and searching by higher level habitat returns taxa that have been defined on lower levels of that habitat. Second part (inside brackets) is optional and can contain one or more specifiers. Use /metadata/ranges/MKV.habitatEnum and /metadata/ranges/MKV.habitatSpecificTypeEnum to find out possible values (schema)
anyHabitat – Same as primaryHabitat, but matches all habitats defined for the taxon.

Red list evaluation data

Taxa API has specific functionality that was needed to implement https://punainenkirja.laji.fi/.

The main difference is the concept of checklistVersion. Different published evaluation periods (2019, 2015, 2010, ..) have been given a different checklistVersion. They can be browsed using /checklistVersion endpoint.

You can check the queries done by punainenkirja.laji.fi for usage examples.