Although biodiversity is much more than just a collection of species, one of the most frequently used entry points into our datasets is the species level (or, to be more precise, any taxon level in general).

When Linnaeus started his work, scientific names were intended to uniquely identify all taxa, which we then could have used as a kind of perfect uuids. Unfortunately, there is neither universal agreement on taxon concepts, nor on their names. In lack of a one-to-one relationship between taxa and their name(s), names and taxa are distinct types of objects. So when looking for a species’ red list status, Norwegian name, textual descriptions, multimedia etc., one first has to find the right taxon.

This is where our Taxon API comes in, of which some of the most common queries are described below. More complete technical documentation can be found on http://artsdatabanken.no/Help.

Accessing the API

  • /Api/Taxon returns information on taxa (including their various names)
  • /Api/Taxon/ScientificName returns information on names (including their taxon)
  • /Api/Taxon/ScientificName/Suggest is where you can get suggestions for names that are similar to your input query. Useful for a “Did you mean…” service.
  • The map API on pavlov.itea.ntnu.no/artskart/Api/Taxon provides quick searching and retrieving of taxa and their names

Name and ID parameters

Once you know the ID of the relevant object, simply append the id to the url.

E.g. /Api/Taxon/83770 for rich taxon info
or /Api/Taxon/ScientificName/48032 for rich name info
or pavlov.itea.ntnu.no/artskart/Api/Taxon/83770 if you only want the name

Use the ScientificName parameter when looking for a specific name.

E.g. /Api/Taxon/ScientificName?ScientificName=Vulpes%20lagopus for the name (synonyms are fine, too)
or /Api/Taxon/ScientificName/Suggest?ScientificName=Vulpez%20lagopos for suggestions
or pavlov.itea.ntnu.no/artskart/Api/Taxon/?term=Fjellrev if you want taxon matches for a (partial) scientific or Norwegian name

Omitting an ID will give you a list.

E.g. /Api/Taxon for all taxa
or /Api/Taxon/ScientificName for all names

Paging parameters

The API’s responses are by default divided into pages of 128 results, which can be accessed through page={page number}, starting from 0. Page size can be modified through pageSize={page size}.

E.g. /Api/Taxon?pageSize=5&page=2 for taxa 11 through 15.

Taxonomic name parameters

There are many kinds of taxa, and usually you are looking for a specific level or ‘rank’, such as species. By adding the taxonRank parameter you can limit the response to the relevant rank.

To look within a specific branch of the tree of life, use the higherClassificationID parameter.

E.g. /Api/Taxon/Scientificname?taxonRank=family&higherClassificationID=296 for all family names within the order of Carnivora

Example

Suppose I want to know whether the Arctic fox is found in Norway, and if so if it is a threatened species.

I am unsure about the name, something like Alopes lagopos or something. So I start with asking for suggestions:

/Api/Taxon/ScientificName/Suggest?scientificname=alopes%20lagopos

The first result is Alopex lagopus, that’s what I meant. I can now look up that name:

/Api/Taxon/ScientificName?scientificname=alopex%20lagopus

There is no red list information (which is connected to names and not taxa) for this name, but the API also says that Alopex lagopus actually is a heterotypic synonym, and that the accepted name should be Vulpes lagopus. Let's look that up:

/Api/Taxon/ScientificName?scientificname=vulpes%20lagopus

In the Dynamic properties I can see that in 2010, the species actually had two red list statuses: LC for Svalbard (Spitsbergen) and CR for Norge (Norway). That probably means the species is found in Norway, but let’s see. I look up the taxon (as it is the species that either does or not exist in Norway and not the name, such information is linked to the actual taxon) with the returned taxonID:

/Api/Taxon/83770

DynamicProperty FinnesINorge has value 1; there are indeed Arctic foxes in Norway!

There is another dynamic property, of the type description. It has its own set of properties, telling me it is a taxon description in Norwegian, with the ID 133470. This I can use to browse to /Pages/133470 and find out more about this animal. Alternatively, /Widgets/133470 returns a widget that I can embed elsewhere.

Other sources

If you want do download entire branches of the tree of life in various formats, you can do so through the export module in our Species Nomenclature Database.

Further reading

Technical documentation: http://artsdatabanken.no/Help

Contact: Wouter Koch