")
158,859 species and infraspecific names are in the database, 22,385 images, 61,541 bibliographic items, 456,692 distributional records.

AlgaeBase API Documentation

Introduction

AlgaeBase data is accessible through our RESTful API to those who have obtained a valid API key. The data is provided – read-only – in JSON format, facilitating the retrieval of species, genus and classification records.
The API endpoint to use is https://api.algaebase.org/v1.2/. Like AlgaeBase itself, the API is a work in progress and adiitional features may be added in the future.

Authentication

A valid key is required to access the API. This key must be passed in the header of each request; typical interaction with the API will take place programmatically through command line applications such as curl:

curl -g -X GET -H "algaebasekey: xxxxxxxxxxxxxxxx" "https://api.algaebase.org/v1.2/"

You can test the API in your browser by installing a plugin such as ModHeader for Chrome that will allow you to send the authentication header along with the request in the URL.
Please contact our lead developer Pier Kuipers if you are interested in obtaining a key.

API Sections

The API endpoint provides two distinct sections:

  • Species – information about AlgaeBase records at the specific and infra-specific level, i.e. species, subspecies, variety and forma.
  • Genus – information at the genus level including full classification.

Metadata Definitions

The API uses universally recognised metadata sets as defined by the Dublin Core Initiative and its subset Darwin Core, as well as some metadata that are unique to AlgaeBase. The query parameters passed to the API as well as the data returned by the API are prefixed with the relevant acronym:

  • Darwin Core – prefixed with dwc: e.g. dwc:scientificname
  • Dublin Core – prefixed with dcterms: e.g. dcterms:modified

Common Parameters

Across all sections of the API there is a set of common parameters that can be applied to the endpoint by means of a query string. The most obvious of these are paging parameters:

Parameter Details
count The number of records displayed in each page. The default is 10 and the maximum is 50.
offset The number of records to be skipped before the current count is displayed.

Combining these two parameters allows large results sets to be retrieved in manageable numbers of pages with equal numbers of results in each page.

Operator Parameters

The API supports the passing of operators alongside parameters in the query string. This allows for very specific queries by specifying operators such as contains, greater than, equal to, etc. The number of operators available depends on the data type of a particular query, for example, searching for year can be finetuned with operators "greater than" and "less than", but not "contains".
Operators are passed in the query string as two characters in square brackets immediately following the equal sign, e.g.

https://api.algaebase.org/v1.2/species?dcterms:creator=[cn]Guiry

In the above example we search for species records that were entered by someone whose name contains "Guiry".
The full range of operators available in the AlgaeBase API is listed below:

Operator Meaning
[CN] Contains
[NC] Does not contain
[BW] Begins with
[EW] Ends with
[EQ] Is equal to
[NE] Is not equal to
[LT] Less than
[GT] Greater than
[LE] Less than or equal to
[GE] Greater than or equal to
[RN] Range (two comma separated values)
[IN] Is contained in (multiple comma separated values)
[NI] Is not conained in (multiple comma separated values)

When using curl to access the database, it is important to note that we should include the --globoff or -g flag to avoid the "globbing" error that is caused by the square brackets in the query string.

Value Lists

Certain fields in the AlgaeBase database can only contain a number of predefined values or enumerations:

Field Value List
dwc:taxonrank species, subspecies (sub, subsp), variety (var), forma (for)
dwc:taxonomicstatus C, S, U, P
(representing Current, Synonym, Uncertain and Provisional)
dwc:nomenclaturalstatus 'nom. cons.', 'nom. illeg.', 'nom. ined.', 'nom. inval.', 'nom. rejic.', 'nom. cons.', 'nom. typificatum', 'nom. descript.', 'nom. et typ. cons.'

Path Parameters

Currently, the only paths available at the API endpoint are species and genus, followed by the ID of a respective record or a query string, e.g.

https://api.algaebase.org/v1.2/species?dcterms:creator=[cn]Guiry
https://api.algaebase.org/v1.2/species/53 
https://api.algaebase.org/v1.2/genus?dwc:scientificName=Haematococcus 
https://api.algaebase.org/v1.2/genus/43375

Query Parameters

A number of query parameters are available for both species and genus, whereas other are unique to their relevant section. Follow the table below for a complete overview.

Key Metadata Definition Level
dcterms:creator An entity primarily responsible for making the resource. Both
dcterms:modified Date on which the resource was changed. Both
dwc:namePublishedInYear The four-digit year in which the scientificName was published. Both
dwc:taxonRank The taxonomic rank of the most specific name in the scientificName. Both
dwc:taxonomicStatus The status of the use of the scientificName as a label for a taxon. Both
dwc:nomenclaturalStatus The status related to the original publication of the name and its conformance to the relevant rules of nomenclature. Both
dwc:scientificNameAuthorship The authorship information for the scientificName formatted according to the conventions of the applicable nomenclatural Code Both
dwc:scientificName The taxon name (with date and authorship information if applicable) Both
dwc:genus The full scientific name of the genus in which the taxon is classified Both
dwc:isFossil ??? Darwin Core? Species
dwc:isFreshwater a boolean flag indicating whether the taxon occurs in freshwater habitats, i.e. can be found in/above rivers or lakes Species
dwc:isMarine a boolean flag indicating whether the taxon is a marine organism, i.e. can be found in/above sea water Species
dwc:isTerrestrial a boolean flag indicating the taxon is a terrestial organism, I.e. occurs on land as opposed to the sea Species
isBrackish a boolean flag indicating whether the taxon is an organism that can be found in brackish water Species
dwc:specificEpithet The name of the first or species epithet of the scientificName. Species
infraspecificEpithet_forma The name of the lowest infraspecific epithet of the scientificName at the rank "forma" Species
infraspecificEpithet_subspecies The name of the lowest infraspecific epithet of the scientificName at the rank "subspecies" Species
infraspecificEpithet_variety The name of the lowest infraspecific epithet of the scientificName at the rank "variety" Species
dwc:scientificNameID Exclusively used to reference an external and resolvable identifier that returns nomenclatural (not taxonomic) details of a name Both
dwc:acceptedNameUsageID The taxonID of the taxon considered to be the accepted name for this nameUsage Both
dwc:originalNameUsageID A unique identifier for the nameUsage instance in which the name was originally established, under the rules of the associated nomenclatural Code. The taxonID of the basionym of the scientificName or the senior/earlier homonym for replaced names. Species
dwc:parentNameUsageID The taxonID of the direct, most proximate higher-rank parent taxon (in a classification) Species
dcterms:URI The set of identifiers constructed according to the generic syntax for Uniform Resource Identifiers as specified by the Internet Engineering Task Force. Both
dcterms:bibliographicCitation A bibliographic reference for the resource. Both

Query Strings

Searching the AlgaeBase database via the API is performed by passing one or more parameters, optionally combined with operators, through a GET request in the URL:

Query Example Explanation
dwc:taxonomicstatus=C search for Current names
dcterms:modified=[ge]2018-01-01

modified on or after the 1st January 2018 (in MySQL format)

dcterms:creator=[bw]Salvador created by user whose name begins with "Salvador"
dwc:isMarine=1 Return marine species only

dcterms:creator=[bw]Salvador& \
dwc:isMarine=1

The above two queries combined

Models

The API will return the data in JSON format using 4 different models, examples of which are provided below:

Species - Object

{
    "dwc:isFossil": null,
    "dwc:specificEpithet": "vermiculata",
    "infraspecificEpithet_variety": null,
    "dwc:scientificNameAuthorship": "(Smith) S.F.Gray",
    "dwc:scientificNameID": 53,
    "dwc:taxonomicStatus": "currently accepted taxonomically",
    "dwc:taxonRank": "species",
    "dwc:parentNameUsageID": 45,
    "dcterms:creator": "M.D. Guiry",
    "infraspecificEpithet_forma": null,
    "infraspecificEpithet_subspecies": null,
    "dwc:namePublishedInYear": "1821",
    "dwc:isFreshwater": null,
    "dwc:genus": "Mesogloia",
    "dwc:isTerrestrial": null,
    "dcterms:URI": "http://www.algaebase.org/search/species/detail/?species_id=w1546c8dbb6324e81",
    "isBrackish": null,
    "dcterms:bibliographicCitation": "Gray, S.F. (1821). A natural arrangement of British plants, according to their relations to each other, as pointed out by Jussieu, De Candolle, Brown, &c. including those cultivated for use; with an introduction to botany, in which the terms newly introduced are explained; illustrated by figures. pp. vol. 1: [i]xxviii, [1] 824, pls I-XXI plates. London: Printed for Baldwin, Cradock & Joy, Paternoster-Row.",
    "dwc:acceptedNameUsageID": 53,
    "dwc:isMarine": 1,
    "dwc:originalNameUsageID": 17414,
    "dcterms:modified": "2015-07-28",
    "dwc:scientificName": "Mesogloia vermiculata (Smith) S.F.Gray Mesogloea",
    "dwc:nomenclaturalStatus": "nom. illeg."
}
                

Genus - Object

{
    "dwc:kingdom": "Plantae",
    "dwc:acceptedNameUsageID": 43375,
    "dcterms:URI": "http://www.algaebase.org/search/genus/detail/?genus_id=A2e6b72e30baf9878",
    "dwc:namePublishedInYear": "1844",
    "dwc:nomenclaturalStatus": "nom. illeg.",
    "dwc:class": "Chlorophyceae",
    "dwc:scientificNameAuthorship": "Flotow",
    "dcterms:bibliographicCitation": "Flotow, J. von (1844). Beobachtungen über Haematococcus pluvialis. Verhandlungen der Kaiserlichen Leopoldinisch-Carolinischen Deutschen Akademie der Naturforscher 12(Abt. 2): 413-606, 3 pls.",
    "dwc:phylum": "Chlorophyta",
    "dwc:order": "Chlamydomonadales",
    "dwc:taxonomicStatus": "currently accepted taxonomically",
    "dwc:scientificNameID": 43375,
    "dwc:taxonRank": "genus",
    "dwc:genus": "Haematococcus",
    "dwc:scientificName": "Haematococcus Flotow, 1844, nom. et typ. cons.",
    "dcterms:creator": "M.D. Guiry",
    "dwc:family": "Haematococcaceae",
    "dcterms:modified": "2016-08-10"
}
                

Classification - Array

"classification": [
    {
        "dwc:taxonID": 86701,
        "dwc:taxonRank": "empire",
        "dwc:scientificName": "Eukaryota"
    },
    {
        "dwc:taxonID": 1,
        "dwc:taxonRank": "kingdom",
        "dwc:scientificName": "Plantae"
    }
    ...
    {
        "dwc:taxonID": 4972,
        "dwc:taxonRank": "family",
        "dwc:scientificName": "Haematococcaceae"
    },
    {
        "dwc:taxonID": 7007,
        "dwc:taxonRank": "genus",
        "dwc:scientificName": "Haematococcus"
    }
]

Navigation – Object

"_pagination": {
    "_next_page": 2,
    "_next_offset": 50,
    "_total_number_of_pages": 2633,
    "_prev_offset": -50,
    "_next_offset_link": "http://api.algaebase.org/v1.2/species/dcterms:creator=[cn]Guiry",
    "_results_per_page(count)": 50,
    "_this_url": "http://api.algaebase.org/v1.2/species?dcterms:creator=[cn]Guiry",
    "_this_page": 1,
    "_prev_offset_link": "http://api.algaebase.org/v1.2/species/dcterms:creator=[cn]Guiry",
    "_total_number_of_results": 131624,
    "_prev_page": 0,
    "_current_offset": 0
}

Website contents © 1996 - 2020 M.D. Guiry. All rights reserved.

Website Design : 249 Design Studio