AlgaeBase API Documentation
Introduction
AlgaeBase data is accessible through our RESTful API to those who have
obtained a valid API key, subject to an annual licence fee depending on
usage but typically €500-1000. 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.3/. Like AlgaeBase itself, the API is a work in progress and additional
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.3/"
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.3/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.3/species?dcterms:creator=[cn]Guiry https://api.algaebase.org/v1.3/species/53 https://api.algaebase.org/v1.3/genus?dwc:scientificName=Haematococcus https://api.algaebase.org/v1.3/genus/43375
Query Parameters and Object Elements
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.
NOTE: As of 1st May 2022, the "dwc" and "dcterms" prefixes should no longer be used in query parameters, they only occur in the response objects returned by the API.
| 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 | Fossil or not | 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 |
|---|---|
| taxonomicstatus=C | search for Current names |
| modified=[ge]2018-01-01 |
modified on or after the 1st January 2018 (in MySQL format) |
| creator=[bw]Salvador | created by user whose name begins with "Salvador" |
| isMarine=1 | Return marine species only |
|
creator=[bw]Salvador&ismarine=true |
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.3/species/dcterms:creator=[cn]Guiry",
"_results_per_page(count)": 50,
"_this_url": "http://api.algaebase.org/v1.3/species?dcterms:creator=[cn]Guiry",
"_this_page": 1,
"_prev_offset_link": "http://api.algaebase.org/v1.3/species/dcterms:creator=[cn]Guiry",
"_total_number_of_results": 131624,
"_prev_page": 0,
"_current_offset": 0
}
