NAV

CoL Clearinghouse API (v1)

http://api.col.plus

Public API of the Clearinghouse for taxonomy and nomenclature. The API currently gives access to staged source datasets for editorial review. The full Catalogue of Life and its versions is handled separately. In addition there is a secured, non public admin API, e.g. to request dataset to be (re)imported.

Data Model

uuid

UUID data type represented as 32 hexadecimal (base 16) digits. Example 123e4567-e89b-12d3-a456-426655440000

isocode

2 or 3 letter codes as used by ISO country or languages

Error

{
  "status": 404,
  "message": "Name 467324, version 7 not found"
}

An error response.

Name Type Pattern Required Description
status integer yes

http status code

message string yes

Error message

ColSource

A citable source for a CoL data provider

Name Type Pattern Required Description
key integer yes

primary key

datasetKey integer yes

key to the dataset this source belongs to

title string yes

Full name of the source. Defaults to dataset title.

alias string yes

Short alias for the source to show in trees etc.

description string no

Free text describing the source supporting markdown formatting

organisation string no

Organisation which has compiled or is owning the source

contactPerson string no

Contact person of the source

authorsAndEditors string[] no

Optional author(s) and editor(s) of the source

version string no

Latest version number of the source used in the Catalogue of Life

released date-only no

Latest release date of the source used in the Catalogue of Life

homepage string no

Homepage URL of the source

group string no

taxonomic group in english language

coverage DatasetType nomenclator, taxonomic, national, personal, other yes

global vs regional sources

citation string no

full bibliographic citation to be used

livingSpeciesCount integer no
livingInfraspecificCount integer no
extinctSpeciesCount integer no
extinctInfraspecificCount integer no
synonymsCount integer no
vernacularsCount integer no
namesCount integer no
created datetime yes

datetime the source was registered in the Clearinghouse

Dataset

Metadata about the source dataset, e.g. a GSD

Name Type Pattern Required Description
key integer yes

Primary key for the source dataset

type DatasetType nomenclator, taxonomic, national, personal, other yes

coarse classification of datasets

title string yes

Full name of the source dataset

gbifKey uuid ^[0-9abcdef]{8}-[0-9abcdef]{4}-[0-9abcdef]{4}-[0-9abcdef]{4}-[0-9abcdef]{12}$ no

GBIF dataset key

gbifPublisherKey uuid ^[0-9abcdef]{8}-[0-9abcdef]{4}-[0-9abcdef]{4}-[0-9abcdef]{4}-[0-9abcdef]{12}$ no

GBIF publisher key in case of GBIF datasets

description string no

Free text describing the source dataset supporting markdown formatting

organisation string no

Organisation which has compiled or is owning the source dataset

contactPerson string no

Contact person of the source dataset

authorsAndEditors string[] no

Optional author(s) and editor(s) of the source dataset

license LicenseType cc0, cc by, cc by nc, unspecified yes

License this dataset falls under

version string no

Latest version number of the source dataset used in the Catalogue of Life

released date-only no

Latest release date of the source dataset used in the Catalogue of Life

homepage string no

Homepage URL of the source

logo string no

URL to a logo image of the dataset

dataFormat enum dwca, tcs, xls, other no

data format

dataAccess string no

URL to access the source data

importFrequency FrequencyType never, once, daily, weekly, monthly, yearly yes

the configured frequency the source is visited for new imports

code NomCodeType bacterial, botanical, cultivated, viral, zoological, unknown no

a default nomenclatural code to be used when importing

catalogue CatalogueType scrutinized, provisional yes

If the dataset participates in any of the 2 catalouge assemblies this is indicated here. All scrutinized sources will also be included as provisional ones. Dataset used to build the provisional catalogue will be trusted and insert their names into the names index.

notes string no

any notes

created datetime yes

datetime the dataset was registered in the Clearinghouse

modified datetime no

datetime the data from this dataset was last changed in the Clearinghouse

deleted datetime no

datetime the dataset was deleted from the Clearinghouse

DatasetImport

{
    "datasetKey": 101,
    "attempt": 1,
    "state": "finished",
    "downloadUri": "https://raw.githubusercontent.com/Sp2000/colplus-repo/master/ACEF/assembly/101.tar.gz",
    "download": "2018-02-28T03:40:02",
    "started": "2018-02-28T03:40:01.433",
    "finished": "2018-02-28T03:52:27.201",
    "verbatimCount": 169988,
    "nameCount": 179025,
    "taxonCount": 147971,
    "referenceCount": 1711,
    "vernacularCount": 0,
    "distributionCount": 137999,
    "issuesCount": {
        "DISTRIBUTION_GAZETEER_INVALID": 3,
        "DISTRIBUTION_STATUS_INVALID": 2,
        "LIFEZONE_INVALID": 1
    },
    "namesByRankCount": {
        "SPECIES": 169988,
        "GENUS": 8878,
        "FAMILY": 155,
        "KINGDOM": 1,
        "PHYLUM": 1,
        "CLASS": 1,
        "ORDER": 1
    },
    "namesByTypeCount": {
        "SCIENTIFIC": 179025
    },
    "distributionsByGazetteerCount": {
        "TEXT": 137999
    },
    "namesByOriginCount": {
        "SOURCE": 169988,
        "DENORMED_CLASSIFICATION": 9037
    }
}

Metrics and import details about a single dataset import event.

Name Type Pattern Required Description
datasetKey integer yes

Primary key for the source dataset

attempt integer yes

Sequential attempt number starting with 1 for each dataset

state ImportState downloading, processing, inserting, unchanged, finished, canceled, failed yes

State of the import, e.g.indicating if still running, success or failure.

downloadUri string yes

Last modification date of the downloaded file

download datetime yes

Last modification date of the downloaded file

started datetime yes

date time the import started

finished datetime no

date time the import finished

error string no

Error message

verbatimCount integer yes

count of all verbatim records

nameCount integer yes

count of all name records

taxonCount integer yes

count of all taxon (accepted name) records

referenceCount integer yes

count of all reference records

vernacularCount integer yes

count of all vernacular names

distributionCount integer yes

count of all distribution records

issuesCount object no

count of verbatim recorbs by issues

namesByRankCount object no

count of names by rank

namesByTypeCount object no

count of names by name type

vernacularsByLanguageCount object no

count of vernacular names by language

distributionsByGazetteerCount object no

count of distributions by gazetteer kind

namesByOriginCount object no

count of names by their origin

usagesByStatusCount object no

count of name usages by their taxonomic status

namesByStatusCount object no

count of names by their name status

nameRelationsByTypeCount object no

count of name relations by their type

verbatimByTypeCount object no

count of verbatim records by their rowType

DatasetResultSet

A paging resultset for Datasets.

Name Type Pattern Required Description
result object[] yes

Result page

offset integer yes

The offset applied during request. Can be less than requested if the limit is reached.

limit integer yes

The maximum number of records returned. Can be less than requested if the limit is reached.

total integer yes

The total number of records available.

results Dataset[] yes

the resulting Datasets

Decision

Name Type Pattern Required Description
key integer yes

primary key

sectorKey integer yes

primary key

subject NameRef yes

the name usage this decision is about

status TaxonomicStatusType accepted, doubtful no

the new status

name string no

the new scientific name

authorship string no

the new authorship

created datetime yes

datetime the decision was created

deleted datetime no

datetime the decision was deleted

Authorship

Name Type Pattern Required Description
authors string[] yes

list of contributing authors

exAuthors string[] no

list of authors excluding ex- authors

year string no

Year of publication

Name

{
    "id": "1000BA50801",
    "datasetKey": 1009,
    "scientificName": "Fomes obliquus",
    "rank": "species",
    "genus": "Fomes",
    "specificEpithet": "obliquus",
    "candidatus": false,
    "combinationAuthorship": {
        "authors": [
            "Cooke"
        ],
        "year": "1885"
    },
    "basionymAuthorship": {
        "authors": [
            "Pers."
        ],
        "exAuthors": [
            "Ach."
        ]
    },
    "origin": "source",
    "type": "scientific",
    "parsed": true,
    "authorship": "(Ach. ex Pers.) Cooke, 1885"
}

A scientific name. CoL deals and categorizes the following types of names:

A name includes it’s authorship. Two homonyms with different authors therefore represent two different name entities.

Lexical variations

The same name can usually be represented by many different strings which we refer to as lexical variations. For each name a standard representation, the canonical form, exists.

Lexical variations exist for various reasons. Author spelling, transliterations, epither gender, additional infrageneric or infraspecific indications, cited species authors in infraspecific names are common reasons. Listed here are 7 distinct names with some of their string representations:

 1. Aus bus Linnaeus 1758
    - Aus bus Linn. 1758
    - Aus bus Linn 1758
    - Aus bus L.
    - Aus ba Linn 1758.
    - Aus (Hus) bus L.

 2. Xus bus (Linn, 1758)
    - Xus bus (Linn) Smith

 3. Xus cus Smith, 1850
    - Xus cus Sm.

 4. Xus cus Jones 1900

 5. Xus bus cus Smith 1850
    - Xus bus subsp. cus Smith 1850

 6. Xus dus Pyle 2000

 7. Foo bar var. lion Smith 1850
    - Foo bar L. var. lion Smith
    - Foo bar subsp. dar var. lion Smith 1850
    - Foo bar Lin. subsp. dar Mill. var. lion Smith 1850

New names (sp./gen. nov.), new recombinations of the same epithet (comb. nov.), a name at a new rank (stat. nov.) or replacement names (nom. nov.) are all treated as distinct names.

Homotypic group & original name

Names based on the same type can be clustered together as a homotypic group of names. A homotypic group not only includes all subsequent recombinations, but also any replacement name if existing. These names are homotypic synonyms, also called nomenclatural or objective synonyms.

The first, originally published name is used to represent such a group as it is a clean proxy to the type specimen, therefore every name in a homotypic group points back to the same original name.

Protonym in zoology and basionym in botany are terms for a very similar concept, but they do not include replacement names and are rather code specific so we will refer to original name here instead, inline with Darwin Core terminology. Original names are not necessarily Code-compliant original descriptions, but usually they are.

The above names can be clustered into four sets of homotypic synonym groups, shown with canonical authorship:

 1. Aus bus Linnaeus 1758
    - Aus ba Linnaeus 1758 [orthographic variant]
    - Xus bus (Linnaeus 1758) Smith 1850 [alternate combination]

 2. Xus cus Smith 1850
    - Xus bus subsp. cus Smith 1850 [alternate rank]

 3. Xus cus Jones 1900 (heterotypic homonym of Xus cus Smith 1850)
    - Xus dus Pyle 2000 [replacement name for Xus cus Jones]

 4. Foo bar var. lion Smith 1850

comb. nov. in ICZN vs ICN

One of the most notable differences between ICN and ICZN is the way names are cited when a species is placed in a different genus from the one it was originally published in (a comb. nov.). Botanists have a convention of always citing the authors of the original combination in brackets followed by the names of the authors of the combination. Zoologists don’t follow this convention, they simply place the author of the original combination in brackets for the new combination and don’t cite the authors who were first to make the new combination. This difference is cosmetic. Indeed ICZN Recommendation 51G is that new combinations in zoology should be quoted in a similar way to the way they are quoted in botany.

Basionym is a well established term in the ICN where it is defined that a “basionym provides the final epithet, name, or stem of the new combination or name at new rank” (ICN Art. 6.10 & Art. 41). It is the orginal combination of a name as viewed from a new combination. The basionym is therefore always relative to a new combination. A name can’t be a basionym in its own right only relative to another name. ICZN does not mention the term basionym but the notion is clearly present in zoological nomenclature as zoologists also have the concept of the new recombination of a name.

Name Type Pattern Required Description
datasetKey integer yes

Key to the source dataset this record belongs to

verbatimKey integer no

Key to the verbatim record this object was derived from

id string yes

Primary id for the record

basionymId string no

link to the original combination. In case of replacement names it points back to the replaced synonym.

scientificName string yes

entire canonical name string with a rank marker for infragenerics and infraspecfics, but excluding the authorship. For uninomials, e.g. families or names at higher ranks, this is just the uninomial.

origin OriginType source, denormed_classification, verbatim_parent, verbatim_accepted, verbatim_basionym, proparte, autonym, implicit_name, missing_accepted, basionym_placeholder, ex_author_synonym, other yes

Enumeration to classify name usages by how they originated

type NameType scientific, virus, hybrid-formula, cultivar, otu, placeholder, none no

Classification of names, mostly based on their syntactic structure

authorship string no

full authorship string including basionym and combination authors, ex- sanctioning authors and years

combinationAuthorship Authorship no

parsed authorship object for this combination

basionymAuthorship Authorship no

parsed authorship of the basionym

sanctioningAuthor string no

the sanctioning author for Fungus names

taxonomicNote string no

informal note often included in authorship that informs about the taxonomic concept. See also Taxon.accordingTo for taxon concept references. Contrary to accordingTo the note here also applies to synonyms such as misapplied names. For example “non Mill.”, “auct. amer.” or “sensu latu”

rank RankType domain, superkingdom, kingdom, subkingdom, infrakingdom, superphylum, phylum, subphylum, infraphylum, superclass, class, subclass, infraclass, parvclass, superlegion, legion, sublegion, infralegion, supercohort, cohort, subcohort, infracohort, magnorder, superorder, grandorder, order, suborder, infraorder, parvorder, superfamily, family, subfamily, infrafamily, supertribe, tribe, subtribe, infratribe, suprageneric name, genus, subgenus, infragenus, supersection, section, subsection, superseries, series, subseries, infrageneric name, species aggregate, species, infraspecific name, grex, subspecies, cultivar group, convariety, infrasubspecific name, proles, natio, aberration, morph, variety, subvariety, form, subform, pathovar, biovar, chemovar, morphovar, phagovar, serovar, chemoform, forma specialis, cultivar, strain, other, unranked yes

rank of the name from enumeration above

code NomCodeType bacterial, botanical, cultivated, viral, zoological, unknown no

code of nomenclature applying to the name

status NomenclaturalStatusType ok, unavailable, illegitimate, variant, conserved, rejected, doubtful, unevaluated no

flag to indicate that this name is available/validly published. Current nomenclatural status of the name taking into account all known nomenclatural acts.

uninomial string no
genus string no

the genus part of a bi- or trinomial name. Not used for genus names which are represented by the scientificName alone.

infragenericEpithet string no

the infrageneric epithet. Used only as the terminal epithet for names at infrageneric ranks, not for species

specificEpithet string no
infraspecificEpithet string no
cultivarEpithet string no
strain string no
candidatus boolean no
notho enum generic, infrageneric, specific, infraspecific no

the part of the name which is considered a hybrid; see GBIF

fossil boolean no

true if the type specimen of the name is a fossil

sourceUrl string no

URL to the taxon webpage in the source.

remarks string no

notes for general remarks on the name, i.e. its nomenclature

NameResultSet

A paging resultset for Names.

Name Type Pattern Required Description
result object[] yes

Result page

offset integer yes

The offset applied during request. Can be less than requested if the limit is reached.

limit integer yes

The maximum number of records returned. Can be less than requested if the limit is reached.

total integer yes

The total number of records available.

results Name[] yes

the resulting names

NameSearchResult

The type of object coming back from a name search query. A NameSearchResult object is a Name object with some extra properties related to synonymy. See below.

Name Type Pattern Required Description
datasetKey integer yes

Key to the source dataset this record belongs to

verbatimKey integer no

Key to the verbatim record this object was derived from

id string yes

Primary id for the record

basionymId string no

link to the original combination. In case of replacement names it points back to the replaced synonym.

scientificName string yes

entire canonical name string with a rank marker for infragenerics and infraspecfics, but excluding the authorship. For uninomials, e.g. families or names at higher ranks, this is just the uninomial.

origin OriginType source, denormed_classification, verbatim_parent, verbatim_accepted, verbatim_basionym, proparte, autonym, implicit_name, missing_accepted, basionym_placeholder, ex_author_synonym, other yes

Enumeration to classify name usages by how they originated

type NameType scientific, virus, hybrid-formula, cultivar, otu, placeholder, none no

Classification of names, mostly based on their syntactic structure

authorship string no

full authorship string including basionym and combination authors, ex- sanctioning authors and years

combinationAuthorship Authorship no

parsed authorship object for this combination

basionymAuthorship Authorship no

parsed authorship of the basionym

sanctioningAuthor string no

the sanctioning author for Fungus names

taxonomicNote string no

informal note often included in authorship that informs about the taxonomic concept. See also Taxon.accordingTo for taxon concept references. Contrary to accordingTo the note here also applies to synonyms such as misapplied names. For example “non Mill.”, “auct. amer.” or “sensu latu”

rank RankType domain, superkingdom, kingdom, subkingdom, infrakingdom, superphylum, phylum, subphylum, infraphylum, superclass, class, subclass, infraclass, parvclass, superlegion, legion, sublegion, infralegion, supercohort, cohort, subcohort, infracohort, magnorder, superorder, grandorder, order, suborder, infraorder, parvorder, superfamily, family, subfamily, infrafamily, supertribe, tribe, subtribe, infratribe, suprageneric name, genus, subgenus, infragenus, supersection, section, subsection, superseries, series, subseries, infrageneric name, species aggregate, species, infraspecific name, grex, subspecies, cultivar group, convariety, infrasubspecific name, proles, natio, aberration, morph, variety, subvariety, form, subform, pathovar, biovar, chemovar, morphovar, phagovar, serovar, chemoform, forma specialis, cultivar, strain, other, unranked yes

rank of the name from enumeration above

code NomCodeType bacterial, botanical, cultivated, viral, zoological, unknown no

code of nomenclature applying to the name

status NomenclaturalStatusType ok, unavailable, illegitimate, variant, conserved, rejected, doubtful, unevaluated no

flag to indicate that this name is available/validly published. Current nomenclatural status of the name taking into account all known nomenclatural acts.

uninomial string no
genus string no

the genus part of a bi- or trinomial name. Not used for genus names which are represented by the scientificName alone.

infragenericEpithet string no

the infrageneric epithet. Used only as the terminal epithet for names at infrageneric ranks, not for species

specificEpithet string no
infraspecificEpithet string no
cultivarEpithet string no
strain string no
candidatus boolean no
notho enum generic, infrageneric, specific, infraspecific no

the part of the name which is considered a hybrid; see GBIF

fossil boolean no

true if the type specimen of the name is a fossil

sourceUrl string no

URL to the taxon webpage in the source.

remarks string no

notes for general remarks on the name, i.e. its nomenclature

acceptedName boolean yes

Whether or not this is an accepted name. If true, the taxa field will be a one-element list containing the Taxon associated with the accepted name. If acceptedName is false, then the name either is a synonym or it is a naked name. If the taxa field is empty, it is a naked name. If the taxa field contains one or more Taxon objects, the name is a synonym, and the taxa field will contain the Taxon objects associated with the accepted names of the synonym.

taxa object[] yes

See above.

NameSearchResultSet

{
    "offset": 0,
    "limit": 10,
    "total": 179025,
    "result": [
        {
            "id": "2157461",
            "datasetKey": 101,
            "scientificName": "Aagaardia",
            "rank": "genus",
            "uninomial": "Aagaardia",
            "candidatus": false,
            "origin": "denormed_classification",
            "type": "scientific",
            "acceptedName": true,
            "taxa": [
                {
                    "id": "1123278",
                    "status": "accepted"
                }
            ],
            "parsed": true
        },
        {
            "id": "Sys-172336",
            "datasetKey": 101,
            "scientificName": "Aagaardia longicalcis",
            "rank": "species",
            "genus": "Aagaardia",
            "specificEpithet": "longicalcis",
            "candidatus": false,
            "combinationAuthorship": {
                "authors": [
                    "Saether"
                ],
                "year": "2000"
            },
            "origin": "source",
            "type": "scientific",
            "acceptedName": true,
            "taxa": [
                {
                    "id": "Sys-172336",
                    "status": "ACCEPTED"
                }
            ],
            "parsed": true,
            "authorship": "Saether, 2000"
        },
        {
            "id": "Sys-196835",
            "datasetKey": 101,
            "scientificName": "Aagaardia oksanae",
            "rank": "species",
            "genus": "Aagaardia",
            "specificEpithet": "oksanae",
            "candidatus": false,
            "combinationAuthorship": {
                "authors": [
                    "Makarchenko"
                ],
                "year": "2005"
            },
            "origin": "source",
            "type": "scientific",
            "acceptedName": true,
            "taxa": [
                {
                    "id": "Sys-196835",
                    "status": "ACCEPTED"
                }
            ],
            "parsed": true,
            "authorship": "Makarchenko, 2005"
        },
        {
            "id": "Sys-172334",
            "datasetKey": 101,
            "scientificName": "Aagaardia protensa",
            "rank": "species",
            "genus": "Aagaardia",
            "specificEpithet": "protensa",
            "candidatus": false,
            "combinationAuthorship": {
                "authors": [
                    "Saether"
                ],
                "year": "2000"
            },
            "origin": "source",
            "type": "scientific",
            "acceptedName": true,
            "taxa": [
                {
                    "id": "Sys-172334",
                    "status": "ACCEPTED"
                }
            ],
            "parsed": true,
            "authorship": "Saether, 2000"
        },
        {
            "id": "Sys-87526",
            "datasetKey": 101,
            "scientificName": "Aagaardia sivertseni",
            "rank": "species",
            "genus": "Aagaardia",
            "specificEpithet": "sivertseni",
            "candidatus": false,
            "basionymAuthorship": {
                "authors": [
                    "Aagaard"
                ],
                "year": "1979"
            },
            "origin": "source",
            "type": "scientific",
            "acceptedName": true,
            "taxa": [
                {
                    "id": "Sys-87526",
                    "status": "accepted"
                }
            ],
            "parsed": true,
            "authorship": "(Aagaard, 1979) "
        },
        {
            "id": "Sys-172335",
            "datasetKey": 101,
            "scientificName": "Aagaardia triangulata",
            "rank": "species",
            "genus": "Aagaardia",
            "specificEpithet": "triangulata",
            "candidatus": false,
            "combinationAuthorship": {
                "authors": [
                    "Saether"
                ],
                "year": "2000"
            },
            "origin": "source",
            "type": "scientific",
            "acceptedName": true,
            "taxa": [
                {
                    "id": "Sys-172335",
                    "status": "ACCEPTED"
                }
            ],
            "parsed": true,
            "authorship": "Saether, 2000"
        },
        {
            "id": "2165044",
            "datasetKey": 101,
            "scientificName": "Abago",
            "rank": "genus",
            "uninomial": "Abago",
            "candidatus": false,
            "origin": "denormed_classification",
            "type": "scientific",
            "acceptedName": true,
            "taxa": [
                {
                    "id": "1114398",
                    "status": "ACCEPTED"
                }
            ],
            "parsed": true
        },
        {
            "id": "Sys-152428",
            "datasetKey": 101,
            "scientificName": "Abago rohdendorfi",
            "rank": "species",
            "genus": "Abago",
            "specificEpithet": "rohdendorfi",
            "candidatus": false,
            "combinationAuthorship": {
                "authors": [
                    "Grunin"
                ],
                "year": "1966"
            },
            "origin": "source",
            "type": "scientific",
            "acceptedName": true,
            "taxa": [
                {
                    "id": "Sys-152428",
                    "status": "ACCEPTED"
                }
            ],
            "parsed": true,
            "authorship": "Grunin, 1966"
        },
        {
            "id": "2159955",
            "datasetKey": 101,
            "scientificName": "Abaristophora",
            "rank": "genus",
            "uninomial": "Abaristophora",
            "candidatus": false,
            "origin": "denormed_classification",
            "type": "scientific",
            "acceptedName": true,
            "taxa": [
                {
                    "id": "1231163",
                    "status": "ACCEPTED"
                }
            ],
            "parsed": true
        },
        {
            "id": "Sys-16345",
            "datasetKey": 101,
            "scientificName": "Abaristophora arctophila",
            "rank": "species",
            "genus": "Abaristophora",
            "specificEpithet": "arctophila",
            "candidatus": false,
            "combinationAuthorship": {
                "authors": [
                    "Schmitz"
                ],
                "year": "1927"
            },
            "origin": "source",
            "type": "scientific",
            "acceptedName": true,
            "taxa": [
                {
                    "id": "Sys-16345",
                    "status": "ACCEPTED"
                }
            ],
            "parsed": true,
            "authorship": "Schmitz, 1927"
        }
    ],
    "last": false
}

A paging resultset for name search results.

Name Type Pattern Required Description
result object[] yes

Result page

offset integer yes

The offset applied during request. Can be less than requested if the limit is reached.

limit integer yes

The maximum number of records returned. Can be less than requested if the limit is reached.

total integer yes

The total number of records available.

NameMatch

A name matching result

Name Type Pattern Required Description
name Name no

the matching name

type MatchType exact, variant, inserted, ambiguous, none yes

the type of matching

alternatives Name[] no

alternatively matching names

NameRef

A reference to a name based on ids and the name itself

Name Type Pattern Required Description
id string yes

the names id within its dataset

indexNameId string no

the name id from the matching name index record

name string yes

the literal name

authorship string no

the literal, full authorship

rank RankType domain, superkingdom, kingdom, subkingdom, infrakingdom, superphylum, phylum, subphylum, infraphylum, superclass, class, subclass, infraclass, parvclass, superlegion, legion, sublegion, infralegion, supercohort, cohort, subcohort, infracohort, magnorder, superorder, grandorder, order, suborder, infraorder, parvorder, superfamily, family, subfamily, infrafamily, supertribe, tribe, subtribe, infratribe, suprageneric name, genus, subgenus, infragenus, supersection, section, subsection, superseries, series, subseries, infrageneric name, species aggregate, species, infraspecific name, grex, subspecies, cultivar group, convariety, infrasubspecific name, proles, natio, aberration, morph, variety, subvariety, form, subform, pathovar, biovar, chemovar, morphovar, phagovar, serovar, chemoform, forma specialis, cultivar, strain, other, unranked no

the rank

NameRelation

{
  "key": 721141,
  "datasetKey": 15,
  "type": "basionym",
  "nameId": "78612",
  "relatedNameId": "1655",
  "publishedInId": "786"
}

A published act which affects the nomenclatural status of a scientific name or the typification of a nominal taxon.

Name Type Pattern Required Description
datasetKey integer yes

Key to the source dataset this record belongs to

verbatimKey integer no

Key to the verbatim record this object was derived from

key integer yes

Primary key for the record

type NameRelationType spelling correction, basionym, based on, replacement name, conserved, later homonym, superfluous, homotypic yes

Coarse classification of the nomenclatural act.

nameId string yes

key to the name the act is about

relatedNameId string no

id to the other, related name

publishedInId string no

Key to reference in which the relation was published

note string no

A desription of the details of the nomenclatural act

Reference

{
  "id": "432561",
  "datasetKey": 15,
  "csl": {
    "DOI":"10.1038/nrd842",
    "type":"article-journal",
    "author":[{"family":"Atkins","given":"Joshua H."},{"family":"Gershell","given":"Leland J."}],
    "title":"From the analyst's couch: Selective anticancer drugs",
    "container-title":"Nature Reviews Drug Discovery",
    "volume":"1",
    "issue":"7",
    "issued":{"date-parts":[[2002,7]]},
    "page":"491-492"
  }
}

A (literature) reference mostly given in CSL-JSON. A reference can be linked to a serial, e.g. a journal, that defines the content for the CSL container attributes.

Treatments are the section of a publication that deals with a single scientific name. They are a unit of citation below articles. Plazi is based on them and Taxon Name Usages (TNU) in GNUB correspond to treatments.

The ability to link to the treatment of a name is very useful. It is accomplished in the NameRelation class, but not dealt with on the shared Reference instances.

Name Type Pattern Required Description
datasetKey integer yes

Key to the source dataset this record belongs to

verbatimKey integer no

Key to the verbatim record this object was derived from

id string yes

Primary id for the record

serialKey integer no

key to container serial

csl object yes

the citation metadata as CSL-JSON, see CSL JSON schema.

ReferenceResultSet

A paging resultset for References.

Name Type Pattern Required Description
result object[] yes

Result page

offset integer yes

The offset applied during request. Can be less than requested if the limit is reached.

limit integer yes

The maximum number of records returned. Can be less than requested if the limit is reached.

total integer yes

The total number of records available.

results Reference[] yes

the resulting References

Sector

A taxonomic sector in the Catalogue of Life

Name Type Pattern Required Description
key integer yes

primary key

colSourceKey integer yes

key to the ColSource this sector originates from

root NameRef yes

A reference to the single root taxon from the col source for this sector. Can even be a species, but usually some higher taxon.

exclude NameRef[] yes

Optional list of taxa within the descendants of root to exclude from this sector definition

attachment NameRef yes

The attachment point in the CoL tree, i.e. the CoL parent taxon for the sector root

suppress NameRef[] yes

Optional list of CoL tree taxa that should be suppressed when this sector is attached. E.g. the CoL management classification might define an alternative taxonomy that uses different taxa which are covered by this sector already.

created datetime yes

datetime the sector was created

deleted datetime no

datetime the sector was deleted

Serial

{
  "key": 432561,
  "datasetKey": 15,
  "bph": "460.06",
  "tl2": "11.084",
  "call": "QK1.J55",
  "oclc": 1754397,
  "bhl": 68922,
  "firstYear": 1799,
  "lastYear": 1804,
  "csl": {
    "call-number": "QK1.J55",
    "type":"journal",
    "title":"Journal für die Botanik",
    "title-short":"J. Bot. (Schrader)",
    "editor":[{"family":"Schrader","given":"H. A."}],
    "publisher-place": "Göttingen"
  }
}

A journal or other serial used as a container for references.

A serial is a publication in any medium issued under the same title in a succession of discrete parts, usually numbered (or dated) and appearing at regular or irregular intervals with no predetermined conclusion. Serial publications include print periodicals and newspapers, electronic magazines and journals, annuals (reports, yearbooks, etc.), proceedings and transactions, and numbered monographic series cataloged separately.

When serials split, merge, or are absorbed, a title change may occur.

A specific serial title is identified by a unique International Standard Serials Number (ISSN) and key title, assigned and maintained by the International Serials Data System (ISDS), a network of national serials data centers. Serials and annuals are listed in Ulrich’s International Periodicals Directory published annually by ProQuest and in The Serials Directory published by EBSCO.

Name Type Pattern Required Description
datasetKey integer yes

Key to the source dataset this record belongs to

aliases string[] no

Alternative titles known for the serial

bph string no

BPH Online identifier. Botanic periodicals published between 1665 and the present.

call string no

library of congress classification number

tl2 string no

TL2 number

oclc integer no

OCLC number

bhl integer no

BHL title number

firstYear integer no

First year the serial was published

lastYear integer no

Last year the serial was published. Empty for current journals

csl object yes

Serial metadata as CSL-JSON, see CSL JSON schema

notes string no

Notes about the serial

SerialResultSet

A paging resultset for Serials.

Name Type Pattern Required Description
result object[] yes

Result page

offset integer yes

The offset applied during request. Can be less than requested if the limit is reached.

limit integer yes

The maximum number of records returned. Can be less than requested if the limit is reached.

total integer yes

The total number of records available.

results Serial[] yes

the resulting Serials

Taxon

{
    "key": 209379,
    "id": "Kew-114621",
    "datasetKey": 24,
    "name": {
        "key": 369744,
        "id": "Kew-114621",
        "datasetKey": 24,
        "scientificName": "Lithocarpus mariae",
        "rank": "species",
        "genus": "Lithocarpus",
        "specificEpithet": "mariae",
        "candidatus": false,
        "combinationAuthorship": {
            "authors": [
                "Soepadmo"
            ]
        },
        "origin": "source",
        "type": "scientific",
        "parsed": true,
        "authorship": "Soepadmo"
    },
    "status": "accepted",
    "origin": "source",
    "parentKey": 209098,
    "accordingTo": "Govaerts R.",
    "fossil": false,
    "recent": true
}

A taxon concept, i.e. an accepted name. Not used for synonyms.

Name Type Pattern Required Description
datasetKey integer yes

Key to the source dataset this record belongs to

verbatimKey integer no

Key to the verbatim record this object was derived from

id string yes

Primary id for the record

name Name yes

the name for this taxon

status TaxonomicStatusType accepted, doubtful yes

the taxonomic status of the taxon

parentKey integer no

key to next higher taxon in the classification

accordingTo string no

person who scrutinized the taxon. LTSSpecialist in the CoL submission format

accordingToDate date-only no

date when the taxon was last scrutinized. LTSDate in the CoL submission format

fossil boolean no

true if the taxon is known from fossil records. NULL if unknown.

recent boolean no

true if the taxon is known from recent, i.e. holocene records. That includes organisms that died out in the last centuries. NULL if unknown.

lifezone LifezoneType[] no

the environment the organism is known to live in.

referenceKeys integer[] no

keys to references supporting the taxon concept.

speciesEstimate integer no

Estimation of total number of species that have been described for this group.

speciesEstimateReferenceKey integer no

Key to reference supporting the estimated number.

remarks string no

notes for general remarks on the taxon

TaxonResultSet

A paging resultset for Taxa.

Name Type Pattern Required Description
result object[] yes

Result page

offset integer yes

The offset applied during request. Can be less than requested if the limit is reached.

limit integer yes

The maximum number of records returned. Can be less than requested if the limit is reached.

total integer yes

The total number of records available.

results Taxon[] yes

the resulting Taxa

TaxonReference

A reference referring to a specific taxon and annotated with a certain topic.

Name Type Pattern Required Description
reference Reference yes
topic ReferenceTopicType[] yes

TaxonInfo

{
    "taxon": {
        "id": "Kew-114621",
        "datasetKey": 24,
        "name": {
            "id": "Kew-114621",
            "datasetKey": 24,
            "scientificName": "Lithocarpus mariae",
            "rank": "species",
            "genus": "Lithocarpus",
            "specificEpithet": "mariae",
            "candidatus": false,
            "combinationAuthorship": {
                "authors": [
                    "Soepadmo"
                ]
            },
            "origin": "source",
            "type": "scientific",
            "parsed": true,
            "authorship": "Soepadmo"
        },
        "status": "accepted",
        "origin": "source",
        "parentId": "209098",
        "accordingTo": "Govaerts R.",
        "fossil": false,
        "recent": true
    },
    "distributions": [
        {
            "datasetKey": 24,
            "area": "Borneo",
            "gazetteer": "tdwg",
            "status": "native"
        }
    ]
}

All supplementarly taxon information for a given taxon.

Name Type Pattern Required Description
taxon Taxon yes
vernacularNames VernacularName[] no
distributions Distribution[] no
taxonReferences string[] no

List of all distinct references supporting the taxon concept, distribution or vernacular names as referenced by the individual record.

references object no

A map of reference keys used by the other objects in this class to the actual full Reference instance.

VerbatimRecord

{
    "key": 114621,
    "datasetKey": 24,
    "line": 4,
    "file": "AcceptedSpecies.txt",
    "type": "acef:AcceptedSpecies",
    "terms": {
        "acef:AuthorString": "Soepadmo",
        "acef:Family": "Fagaceae",
        "acef:AcceptedTaxonID": "Kew-114621",
        "acef:Phylum": "Tracheophyta",
        "acef:LTSDate": "Aug-2017",
        "acef:Sp2000NameStatus": "accepted name",
        "acef:LTSSpecialist": "Govaerts R.",
        "acef:HasModern": "1",
        "acef:SpeciesEpithet": "mariae",
        "acef:Kingdom": "Plantae",
        "acef:Order": "Fagales",
        "acef:Genus": "Lithocarpus",
        "acef:HasPreHolocene": "0",
        "acef:Class": "Magnoliopsida",
        "acef:IsExtinct": "0"
    },
    "issues": [
        "according to date invalid",
        "escaped characters"
    ]
}

Verbatim version of the entire source record with issues flagged during processing.

Name Type Pattern Required Description
datasetKey integer yes

Key to the source dataset this record belongs to

key integer yes

Internal primary key

line integer yes

The line number of the file this record originated from

file string yes

The name of the file this record originated from

type string yes

The rowType (class) term of the file this record originated from

terms object yes

Map of DwC or ACEF terms to their string value

issues IssueType[] no

Set of issues spotted during processing

VerbatimRecordResultSet

A paging resultset for VerbatimRecords.

Name Type Pattern Required Description
result object[] yes

Result page

offset integer yes

The offset applied during request. Can be less than requested if the limit is reached.

limit integer yes

The maximum number of records returned. Can be less than requested if the limit is reached.

total integer yes

The total number of records available.

results VerbatimRecord[] yes

the resulting VerbatimRecords

VernacularName

A vernacular name

Name Type Pattern Required Description
datasetKey integer yes

Key to the source dataset this record belongs to

name string yes

the vernacular name

latin string yes

transliterated vernacular name into the latin script

language isocode ^[a-z]{2,3}$ yes

the language given as 3 letter ISO codes

country isocode ^[a-z]{2,3}$ yes

the country given as 2 letter ISO codes

referenceIds string[] yes

Links to references supporting the vernacular name record

Distribution

An area distribution record

Name Type Pattern Required Description
datasetKey integer yes

Key to the source dataset this record belongs to

area string yes

the geographic area the distribution refers to as defined in the corresponding area standard.

gazetteer GazetteerType tdwg, iso, fao, fao-fishing, longhurst, teow, iho, text yes

The standard of area names the area value refers to.

status DistributionStatusType native, domesticated, alien, uncertain yes

The status of the species distribution

referenceIds string[] no

Links to references supporting the distribution record

Vocabularies

CatalogueType

Enumeration: scrutinized, provisional

Assembled catalogues in the CoL See http://api.col.plus/vocab/catalogue for the latest full list.

DatasetType

Enumeration: nomenclator, taxonomic, national, personal, other

Enumeration of kind of datasets See http://api.col.plus/vocab/datasettype for the latest full list.

DistributionStatusType

Enumeration: native, domesticated, alien, uncertain

CoL distribution status enumeration See http://api.col.plus/vocab/distributionstatus

FrequencyType

Enumeration: never, once, daily, weekly, monthly, yearly

Enumeration of frequencies for scheduling dataset imports. See http://api.col.plus/vocab/frequency for the latest full list.

GazetteerType

Enumeration: tdwg, iso, fao, fao-fishing, longhurst, teow, iho, text

List of supported distribution area standards. See http://api.col.plus/vocab/gazetteer

tdwg
World Geographical Scheme for Recording Plant Distributions published by TDWG at level 3 or 4.
iso
ISO 3166-1 country codes given either as alpha-2, alpha-3 or numeric codes
fao
FAO ISO codes
fao-fishing
FAO Fishing Areas
longhurst
Longhurst Biogeographical Provinces, a partition of the world oceans into provinces as defined by Longhurst, A.R. (2006). Ecological Geography of the Sea. 2nd Edition.
teow
Terrestrial Ecoregions of the World (TEOW) is a biogeographic regionalization of the Earth’s terrestrial biodiversity. See Olson et al. 2001. Terrestrial ecoregions of the world: a new map of life on Earth. Bioscience 51(11):933-938.
iho
IAO sea areas as boundaries of the major oceans and seas of the world. See Limits of Oceans & Seas, Special Publication No. 23 published by the International Hydrographic Organization in 1953.
text
Free text not following any standard

ImportState

Enumeration: downloading, processing, inserting, unchanged, finished, canceled, failed

Enumeration of states of running or finished dataset imports. See http://api.col.plus/vocab/importstate for the latest full list.

IssueType

Enumeration: unparsable name, partially parsable name, unparsable authorship, doubtful name, inconsistent authorship, inconsistent name, unusual characters, null epithet, subspecies assigned, lc monomial, indet cultivar, indet species, indet infraspecies, higher rank binomial, question marks removed, repl enclosing quote, missing genus, escaped characters, nomenclatural status invalid, nomenclatural code invalid, basionym author mismatch, basionym not unique, basionym derived, conflicting basionym combination, potential orthographic variant, homonym, published before genus, reference id invalid, id not unique, parent id invalid, accepted id invalid, basionym id invalid, accepted name missing, rank invalid, taxonomic status invalid, lifezone invalid, is fossil invalid, is recent invalid, url invalid, according to date invalid, chained synoym, taxonomic status mismatch, parent cycle, classification rank order invalid, classification not applied, vernacular name invalid, vernacular name transliterated, description invalid, distribution invalid, distribution area invalid, distribution country invalid, distribution status invalid, distribution gazeteer invalid, species profile invalid, multimedia invalid, bib reference invalid, alt identifier invalid, backbone match none, backbone match fuzzy, name not unique, parent name not unique, relationship missing, no species, name parent mismatch, orthographic variant

Issues that the Clearinghouse software is able to detect and flag a Taxon, Name or Reference with. The enumeration is in very active development and extended as new rules are implemented. Not all flagged issues are highlighting data problems. Some simply flag the fact that data was modified during imports, for example “vernacular name transliterated” is added then a latin transliteration of a vernacular name was automatically generated. See http://api.col.plus/vocab/issue for the latest full list.

KingdomType

Enumeration: Animalia, Archaea, Bacteria, Chromista, Fungi, Plantae, Protozoa, Viruses

Enumeration of all kingdoms recognized in the Catalogue of Life. See http://api.col.plus/vocab/kingdom

LicenseType

Enumeration: cc0, cc by, cc by nc, unspecified

Enumeration of Creative Commons license types supported by the Clearinghouse. See http://api.col.plus/vocab/license

LifezoneType

Enumeration: brackish, freshwater, marine, terrestrial

Coarse classification of the environment an organism lives in. See http://api.col.plus/vocab/lifezone

MatchType

Enumeration: exact, variant, inserted, ambiguous, none

Enumeration of the kind of matches possible.

NameRelationType

Enumeration: spelling correction, basionym, based on, replacement name, conserved, later homonym, superfluous, homotypic

Coarse classification of nomenclatural name relations. See http://api.col.plus/vocab/nomreltype

spelling correction
The current name is a spelling correction, called emendation in zoology, of the related name having the same type. Intentional changes in the original spelling of an available name, whether justified or unjustified. The binomial authority remains unchanged. Valid emendations include changes made to correct: a) typographical errors in the original work describing the species, b) errors in transliteration from non-Latin languages, c) names that included diacritics, hyphens d) endings of species to match the gender of the generic name, particularly when the combination has been changed

For example, Hieronima and Hyeronima are orthographical variants of Hieronyma. One of the spellings must be treated as the correct one. In this case, the spelling Hieronyma has been conserved and is to be used as the correct spelling.

Botany (Article 61).: An inadvertent use of one of the other spellings has no consequences: the name is to be treated as if it were correctly spelled.

Zoology (Art. 32-33 ): Orthographical variants in the formal sense do not exist; a misspelling or orthographic error is treated as a lapsus, a form of inadvertent error. The first reviser is allowed to choose one variant for mandatory further use, but in other ways, these errors generally have no further formal standing.

basionym
The current name has a basionym and therefore is either a recombination (combinatio nova, comb. nov.) of the name pointed to (and the name pointed to is not, itself, a recombination), or a change in rank (status novus, stat. nov.).
based on
The current name is the validation of a name that was not fully published before. Covers the use of ex in botanical author strings.

ICN Art. 46.4: e.g. if this name object represents G. tomentosum Nutt. ex Seem. then the related name should be G. tomentosum Nutt.

replacement name
Current name is replacement for the related name. Also called ‘Nomen Novum’ or ‘avowed substitute’ ICN: Article 7.3 ICZN: Article 60.3.
conserved
The current name or spelling is conserved / protected against the related name or the related name is suppressed / rejected in favor of the current name.

A spelling which has been conserved relates two homotypic names, otherwise the related names should be based on different types.

Based on an individual publication but more often due to actions of the ICZN or ICBN exercising its Plenary Powers.

ICN: Conservation is covered under Article 14 and Appendix II and Appendix III (this name is nomina conservanda). ICZN: Reversal of precedence under Article 23.9 (this name is nomen protectum and the target name is nomen oblitum) or suppression via plenary power Article 81.

later homonym
Current name has same spelling as related name but was published later and has priority over it (unless conserved or sanctioned) and is based on a different type. Called a junior homonym in zoology. This includes botanical parahomonyms which differ slightly in spelling but are similar enough that they are likely to be confused (Art 53.3). The zoological code has a set of spelling variations (article 58) that are considered to be identical. When acts of conservation or suppression have occurred then the terms ’Conserved Later Homonym’and ‘Rejected Earlier Homonym’ should be used. Two identical and homotypic names (isonyms) should be indicated with the superfluous relation type. ICN: Article 53 ICZN: Chapter 12, Article 52.
superfluous
Current name was superfluous at its time of publication, i. e. it was based on the same type as the related, previously published name (ICN article 52). The current, superfluous name is available but illegitimate. Includes the special case of isonyms which are identical names.
homotypic
A relation indicating two homotypic names, i.e. objective or nomenclatural synonymy, but not further specifying why.

NameType

Enumeration: scientific, virus, hybrid-formula, cultivar, otu, placeholder, none

Classification of names, mostly based on their syntactic structure. See http://api.col.plus/vocab/nametype

NomCodeType

Enumeration: bacterial, botanical, cultivated, viral, zoological, unknown

Nomenclatural code enumeration regardless of the exact version published. See http://api.col.plus/vocab/nomcode bacteriological : Bacteriological code botanical : Botanical code cultivated : Cultivated Plants viral : viral, zoological : zoological code

NomenclaturalStatusType

Enumeration: ok, unavailable, illegitimate, variant, conserved, rejected, doubtful, unevaluated

The status related to the latest nomenclatural act published for the name and its conformance to the rules of nomenclature. See http://api.col.plus/vocab/nomstatus Generic nomenclatural status enumeration across all codes. Only the broader status concepts are captured and details of the nomenclatural status of a name should be given as free text. The overloaded term “valid” is avoided as it carries different semantics in the botanical and zoological code. Rendering of the status can be different between codes and some values only apply to certain codes. ok : TODO: probably a better term should be coined : Botany - Names that are validly published and legitimate : Zoology - Available name and potentially valid, i.e. not otherwise invalid for any other objective reason, such as being a junior homonym. unavailable : Botany - Names that are not validly published (nom. inval.) : Zoology - An unavailable name published not conforming to all the mandatory provisions of the International Code of Zoological Nomenclature. illegitimate : Botany - A validly published name which is a later homonym, superfluous, or rejected (nom. illeg.) : Zoology - Available, but objectively invalid names, e.g. junior homonym or objective synonyms variant : Orthographic variant. An alternative or corrected spelling for the name (orth. var.) replacement : A nomen novum, replacement name or new substitute name indicates a scientific name that is created specifically to replace another preoccupied name, but only when this other name can not be used for technical, nomenclatural reasons. It automatically inherits the same type and type locality and is commonly applied to names proposed to replace junior homonyms

conserved : Botany - A validly published name which is listed in the ICN appendices of conserved names (nom. cons.) : Zoology - rejected : Botany - A validly published name listed as rejected by ICN – includes utique rejiciendum and opera oppressa (nom. rej.) : Zoology - doubtful : Unknown or doubtful names (nom. dub.) unevaluated : if the name status has not been evaluated yet

OriginType

Enumeration: source, denormed_classification, verbatim_parent, verbatim_accepted, verbatim_basionym, proparte, autonym, implicit_name, missing_accepted, basionym_placeholder, ex_author_synonym, other

Enumeration of the kind of matches possible. See http://api.col.plus/vocab/origin

RankType

Enumeration: domain, superkingdom, kingdom, subkingdom, infrakingdom, superphylum, phylum, subphylum, infraphylum, superclass, class, subclass, infraclass, parvclass, superlegion, legion, sublegion, infralegion, supercohort, cohort, subcohort, infracohort, magnorder, superorder, grandorder, order, suborder, infraorder, parvorder, superfamily, family, subfamily, infrafamily, supertribe, tribe, subtribe, infratribe, suprageneric name, genus, subgenus, infragenus, supersection, section, subsection, superseries, series, subseries, infrageneric name, species aggregate, species, infraspecific name, grex, subspecies, cultivar group, convariety, infrasubspecific name, proles, natio, aberration, morph, variety, subvariety, form, subform, pathovar, biovar, chemovar, morphovar, phagovar, serovar, chemoform, forma specialis, cultivar, strain, other, unranked

Enumeration of all possible rank values across all codes. See http://api.col.plus/vocab/rank for the complete list in use There is the need to deal with old ranks not accepted anymore. The list given is intended to be interoperable between name providers for bacteria, viruses, fungi, plants, and animals. The enumeration attempts to strike a balance between listing all possible rank terms, and remaining comprehensible. Not included in the list are the botanical “notho-” ranks, which are used to designate hybrids (nothospecies, nothogenus) as this information is handled by the Name.notho property already. Sources:

TODO: extract all values from sources

ReferenceTopicType

Enumeration: nomen, taxon, vernacular, distribution

Enumeration of types of CoL relevant information that is treated in a publication See http://api.col.plus/vocab/gazetteer

TaxonomicStatusType

Enumeration: accepted, doubtful

Taxonomic status enumeration for both accepted taxa and synonyms. See http://api.col.plus/vocab/taxonomicstatus

Authentication

/dataset


GET //dataset HTTP/1.1
Host: api.col.plus

GET http://api.col.plus/dataset

Paging parameters.

Parameters

Name Type Pattern Required Default Description
offset integer no

The requested number of offset records. Defaults to zero

limit integer no

The requested number of maximum records to be returned. Defaults to 10 and can be no more than 1000.

q string yes

full text search query

Response 200


HTTP/1.1 200 OK
Date: Wednesday, November 7, 2018 4:02:17 PM CET
Content-Type: application/json

application/json

Content: DatasetResultSet


POST //dataset HTTP/1.1
Host: api.col.plus
Content-Type: application/json

POST http://api.col.plus/dataset

Creates a new dataset specified through the JSON request body and returns the database key of the new dataset.

Body

application/json

Content: Dataset

Response 201


HTTP/1.1 201 Created
Date: Wednesday, November 7, 2018 4:02:17 PM CET
Content-Type: application/json

application/json

Content: integer

/dataset/{dkey}


GET //dataset/{dkey} HTTP/1.1
Host: api.col.plus

GET http://api.col.plus/dataset/{dkey}

Retrieves the dataset with the specified key.

Parameters

Name Type Pattern Required Default Description
{dkey} integer yes

dataset key

Response 200


HTTP/1.1 200 OK
Date: Wednesday, November 7, 2018 4:02:17 PM CET
Content-Type: application/json

application/json

Content: Dataset


DELETE //dataset/{dkey} HTTP/1.1
Host: api.col.plus

DELETE http://api.col.plus/dataset/{dkey}

Deletes the dataset with the specified database key.

Parameters

Name Type Pattern Required Default Description
{dkey} integer yes

dataset key

Response 204

Dataset deleted.

Response 404

Specified key does not exist.


PUT //dataset/{dkey} HTTP/1.1
Host: api.col.plus

PUT http://api.col.plus/dataset/{dkey}

Updates the dataset specified through the JSON request body.

Parameters

Name Type Pattern Required Default Description
{dkey} integer yes

dataset key

Response 204

Response 404

/dataset/{dkey}/import


GET //dataset/{dkey}/import HTTP/1.1
Host: api.col.plus

GET http://api.col.plus/dataset/{dkey}/import

Retrieve import metrics for the dataset with the specified key. By default just returns the last import

Parameters

Name Type Pattern Required Default Description
limit integer yes

number of imports to limit to. Defaults to 1.

state ImportState downloading, processing, inserting, unchanged, finished, canceled, failed yes

filters listed import metrics by their state, e.g. the last failed import

Response 200


HTTP/1.1 200 OK
Date: Wednesday, November 7, 2018 4:02:17 PM CET
Content-Type: application/json

    [{
    "datasetKey": 101,
    "attempt": 1,
    "state": "finished",
    "downloadUri": "https://raw.githubusercontent.com/Sp2000/colplus-repo/master/ACEF/assembly/101.tar.gz",
    "download": "2018-02-28T03:40:02",
    "started": "2018-02-28T03:40:01.433",
    "finished": "2018-02-28T03:52:27.201",
    "verbatimCount": 169988,
    "nameCount": 179025,
    "taxonCount": 147971,
    "referenceCount": 1711,
    "vernacularCount": 0,
    "distributionCount": 137999,
    "issuesCount": {
        "DISTRIBUTION_GAZETEER_INVALID": 3,
        "DISTRIBUTION_STATUS_INVALID": 2,
        "LIFEZONE_INVALID": 1
    },
    "namesByRankCount": {
        "SPECIES": 169988,
        "GENUS": 8878,
        "FAMILY": 155,
        "KINGDOM": 1,
        "PHYLUM": 1,
        "CLASS": 1,
        "ORDER": 1
    },
    "namesByTypeCount": {
        "SCIENTIFIC": 179025
    },
    "distributionsByGazetteerCount": {
        "TEXT": 137999
    },
    "namesByOriginCount": {
        "SOURCE": 169988,
        "DENORMED_CLASSIFICATION": 9037
    }
}
,{
    "datasetKey": 101,
    "attempt": 1,
    "state": "finished",
    "downloadUri": "https://raw.githubusercontent.com/Sp2000/colplus-repo/master/ACEF/assembly/101.tar.gz",
    "download": "2018-02-28T03:40:02",
    "started": "2018-02-28T03:40:01.433",
    "finished": "2018-02-28T03:52:27.201",
    "verbatimCount": 169988,
    "nameCount": 179025,
    "taxonCount": 147971,
    "referenceCount": 1711,
    "vernacularCount": 0,
    "distributionCount": 137999,
    "issuesCount": {
        "DISTRIBUTION_GAZETEER_INVALID": 3,
        "DISTRIBUTION_STATUS_INVALID": 2,
        "LIFEZONE_INVALID": 1
    },
    "namesByRankCount": {
        "SPECIES": 169988,
        "GENUS": 8878,
        "FAMILY": 155,
        "KINGDOM": 1,
        "PHYLUM": 1,
        "CLASS": 1,
        "ORDER": 1
    },
    "namesByTypeCount": {
        "SCIENTIFIC": 179025
    },
    "distributionsByGazetteerCount": {
        "TEXT": 137999
    },
    "namesByOriginCount": {
        "SOURCE": 169988,
        "DENORMED_CLASSIFICATION": 9037
    }
}
]

application/json

Content: DatasetImport[]

/dataset/{dkey}/verbatim


GET //dataset/{dkey}/verbatim HTTP/1.1
Host: api.col.plus

GET http://api.col.plus/dataset/{dkey}/verbatim

Page through all verbatim records of the dataset

Parameters

Name Type Pattern Required Default Description
type string yes

Optional filter by rowType of verbatim record, i.e. which file

offset integer no

The requested number of offset records. Defaults to zero

limit integer no

The requested number of maximum records to be returned. Defaults to 10 and can be no more than 1000.

Response 200


HTTP/1.1 200 OK
Date: Wednesday, November 7, 2018 4:02:17 PM CET
Content-Type: application/json

application/json

Content: VerbatimRecordResultSet

/dataset/{dkey}/verbatim/{key}


GET //dataset/{dkey}/verbatim/{key} HTTP/1.1
Host: api.col.plus

GET http://api.col.plus/dataset/{dkey}/verbatim/{key}

Get the verbatim representation of a source record by its dwca core id

Parameters

Name Type Pattern Required Default Description
{key} string yes

internal key of the record

Response 200


HTTP/1.1 200 OK
Date: Wednesday, November 7, 2018 4:02:17 PM CET
Content-Type: application/json

    {
    "key": 114621,
    "datasetKey": 24,
    "line": 4,
    "file": "AcceptedSpecies.txt",
    "type": "acef:AcceptedSpecies",
    "terms": {
        "acef:AuthorString": "Soepadmo",
        "acef:Family": "Fagaceae",
        "acef:AcceptedTaxonID": "Kew-114621",
        "acef:Phylum": "Tracheophyta",
        "acef:LTSDate": "Aug-2017",
        "acef:Sp2000NameStatus": "accepted name",
        "acef:LTSSpecialist": "Govaerts R.",
        "acef:HasModern": "1",
        "acef:SpeciesEpithet": "mariae",
        "acef:Kingdom": "Plantae",
        "acef:Order": "Fagales",
        "acef:Genus": "Lithocarpus",
        "acef:HasPreHolocene": "0",
        "acef:Class": "Magnoliopsida",
        "acef:IsExtinct": "0"
    },
    "issues": [
        "according to date invalid",
        "escaped characters"
    ]
}

application/json

Content: VerbatimRecord

/dataset/{dkey}/taxon


GET //dataset/{dkey}/taxon HTTP/1.1
Host: api.col.plus

GET http://api.col.plus/dataset/{dkey}/taxon

Paging parameters.

Parameters

Name Type Pattern Required Default Description
nameKey integer no

The database key of the name associated with the requested taxa

root boolean no

Whether or not to only retrieve root taxa

offset integer no

The requested number of offset records. Defaults to zero

limit integer no

The requested number of maximum records to be returned. Defaults to 10 and can be no more than 1000.

datasetKey string yes

The database key of the dataset

Response 200


HTTP/1.1 200 OK
Date: Wednesday, November 7, 2018 4:02:17 PM CET
Content-Type: application/json

application/json

Content: ResultSet

/dataset/{dkey}/taxon/{id}


GET //dataset/{dkey}/taxon/{id} HTTP/1.1
Host: api.col.plus

GET http://api.col.plus/dataset/{dkey}/taxon/{id}

Retrieves the taxon with the specified id.

Parameters

Name Type Pattern Required Default Description
{id} string yes

taxon identifier as coming from the source

Response 200


HTTP/1.1 200 OK
Date: Wednesday, November 7, 2018 4:02:17 PM CET
Content-Type: application/json

    {
    "key": 209379,
    "id": "Kew-114621",
    "datasetKey": 24,
    "name": {
        "key": 369744,
        "id": "Kew-114621",
        "datasetKey": 24,
        "scientificName": "Lithocarpus mariae",
        "rank": "species",
        "genus": "Lithocarpus",
        "specificEpithet": "mariae",
        "candidatus": false,
        "combinationAuthorship": {
            "authors": [
                "Soepadmo"
            ]
        },
        "origin": "source",
        "type": "scientific",
        "parsed": true,
        "authorship": "Soepadmo"
    },
    "status": "accepted",
    "origin": "source",
    "parentKey": 209098,
    "accordingTo": "Govaerts R.",
    "fossil": false,
    "recent": true
}

application/json

Content: Taxon

/dataset/{dkey}/taxon/{id}/info


GET //dataset/{dkey}/taxon/{id}/info HTTP/1.1
Host: api.col.plus

GET http://api.col.plus/dataset/{dkey}/taxon/{id}/info

Returns a TaxonInfo object containing all details about the taxon with the specified key and its supplementary information.

Response 200


HTTP/1.1 200 OK
Date: Wednesday, November 7, 2018 4:02:17 PM CET
Content-Type: application/json

    {
    "taxon": {
        "id": "Kew-114621",
        "datasetKey": 24,
        "name": {
            "id": "Kew-114621",
            "datasetKey": 24,
            "scientificName": "Lithocarpus mariae",
            "rank": "species",
            "genus": "Lithocarpus",
            "specificEpithet": "mariae",
            "candidatus": false,
            "combinationAuthorship": {
                "authors": [
                    "Soepadmo"
                ]
            },
            "origin": "source",
            "type": "scientific",
            "parsed": true,
            "authorship": "Soepadmo"
        },
        "status": "accepted",
        "origin": "source",
        "parentId": "209098",
        "accordingTo": "Govaerts R.",
        "fossil": false,
        "recent": true
    },
    "distributions": [
        {
            "datasetKey": 24,
            "area": "Borneo",
            "gazetteer": "tdwg",
            "status": "native"
        }
    ]
}

application/json

Content: TaxonInfo

/dataset/{dkey}/taxon/{id}/classification


GET //dataset/{dkey}/taxon/{id}/classification HTTP/1.1
Host: api.col.plus

GET http://api.col.plus/dataset/{dkey}/taxon/{id}/classification

Returns the taxonomic ancestry of the taxon with the specified key, i.e. all ancestral taxa up to the taxon’s kingdom starting with the direct parent taxon.

Response 200


HTTP/1.1 200 OK
Date: Wednesday, November 7, 2018 4:02:17 PM CET
Content-Type: application/json

    [{
    "key": 209379,
    "id": "Kew-114621",
    "datasetKey": 24,
    "name": {
        "key": 369744,
        "id": "Kew-114621",
        "datasetKey": 24,
        "scientificName": "Lithocarpus mariae",
        "rank": "species",
        "genus": "Lithocarpus",
        "specificEpithet": "mariae",
        "candidatus": false,
        "combinationAuthorship": {
            "authors": [
                "Soepadmo"
            ]
        },
        "origin": "source",
        "type": "scientific",
        "parsed": true,
        "authorship": "Soepadmo"
    },
    "status": "accepted",
    "origin": "source",
    "parentKey": 209098,
    "accordingTo": "Govaerts R.",
    "fossil": false,
    "recent": true
}
,{
    "key": 209379,
    "id": "Kew-114621",
    "datasetKey": 24,
    "name": {
        "key": 369744,
        "id": "Kew-114621",
        "datasetKey": 24,
        "scientificName": "Lithocarpus mariae",
        "rank": "species",
        "genus": "Lithocarpus",
        "specificEpithet": "mariae",
        "candidatus": false,
        "combinationAuthorship": {
            "authors": [
                "Soepadmo"
            ]
        },
        "origin": "source",
        "type": "scientific",
        "parsed": true,
        "authorship": "Soepadmo"
    },
    "status": "accepted",
    "origin": "source",
    "parentKey": 209098,
    "accordingTo": "Govaerts R.",
    "fossil": false,
    "recent": true
}
]

application/json

Content: Taxon[]

/dataset/{dkey}/taxon/{id}/children


GET //dataset/{dkey}/taxon/{id}/children HTTP/1.1
Host: api.col.plus

GET http://api.col.plus/dataset/{dkey}/taxon/{id}/children

Page through all direct children of the taxon regardless of the rank.

Response 200


HTTP/1.1 200 OK
Date: Wednesday, November 7, 2018 4:02:17 PM CET
Content-Type: application/json

application/json

Content: TaxonResultSet

/dataset/{dkey}/taxon/{id}/synonyms


GET //dataset/{dkey}/taxon/{id}/synonyms HTTP/1.1
Host: api.col.plus

GET http://api.col.plus/dataset/{dkey}/taxon/{id}/synonyms

get list of all synonyms chronologically arranged by homotypic groups. Nested homotypic names are based on the same original name in sublists. Example given for synonymy of Agoseris grandiflora (Nutt.) Greene Example: Barkhausia lessingii Hook. & Arn. nom. illeg. is a homotypical synonym of Agoseris apargioides (Less.) Greene

Response 200


HTTP/1.1 200 OK
Date: Wednesday, November 7, 2018 4:02:17 PM CET
Content-Type: application/json

    [
    [
        {
            "id": "21242",
            "datasetKey": 15,
            "scientificName": "Stylopappus grandiflorus",
            "scientificNameID": "abc0001",
            "authorship": "Nutt.",
            "combinationAuthorship": {
              "authors": ["Nutt."],
              "year": "1841"
            },
            "origin": "source",
            "rank": "species",
            "nomenclaturalCode": "botanical",
            "genus": "Stylopappus",
            "specificEpithet": "grandiflorus",
            "basionymKey": 21242
         },
        {
            "id": "21243",
            "datasetKey": 15,
            "scientificName": "Macrorhynchus grandiflorus",
            "scientificNameID": "abc0002",
            "authorship": "(Nutt.) Torr. & A. Gray",
            "basionymAuthorship": {
              "authors": ["Nutt."]
            },
            "combinationAuthorship": {
              "authors": ["Torr.", "A. Gray"],
              "year": "1843"
            },
            "origin": "source",
            "rank": "species",
            "nomenclaturalCode": "botanical",
            "genus": "Stylopappus",
            "specificEpithet": "grandiflorus",
            "basionymKey": 21242
        },
        {
            "id": "21244",
            "datasetKey": 15,
            "scientificName": "Troximon grandiflorum",
            "scientificNameID": "abc0003",
            "authorship": "(Nutt.) A. Gray",
            "basionymAuthorship": {
              "authors": ["Nutt."]
            },
            "combinationAuthorship": {
              "authors": ["A. Gray"],
              "year": "1874"
            },
            "origin": "source",
            "rank": "species",
            "nomenclaturalCode": "botanical",
            "genus": "Troximon",
            "specificEpithet": "grandiflorum",
            "basionymKey": 21242
         }
    ],
    [
        {
            "id": "13078",
            "datasetKey": 15,
            "scientificName": "Troximon marshallii",
            "scientificNameID": "abc0004",
            "authorship": "Greene",
            "combinationAuthorship": {
              "authors": ["Greene"],
              "year": "1888"
            },
            "origin": "source",
            "rank": "species",
            "nomenclaturalCode": "botanical",
            "genus": "Troximon",
            "specificEpithet": "marshallii"
        },
        {
            "id": "13079",
            "datasetKey": 15,
            "scientificName": "Agoseris marshallii",
            "scientificNameID": "abc0005",
            "authorship": "(Greene) Greene",
            "basionymAuthorship": {
              "authors": ["Greene"]
            },
            "combinationAuthorship": {
              "authors": ["Greene"],
              "year": "1891"
            },
            "origin": "source",
            "rank": "species",
            "nomenclaturalCode": "botanical",
            "genus": "Agoseris",
            "specificEpithet": "marshallii",
            "basionymKey": 13078
        },
        {
            "id": "13080",
            "datasetKey": 15,
            "scientificName": "Agoseris marshalii",
            "scientificNameID": "abc0006",
            "authorship": "(Greene) Greene",
            "basionymAuthorship": {
              "authors": ["Greene"]
            },
            "combinationAuthorship": {
              "authors": ["Greene"],
              "year": "1891"
            },
            "origin": "source",
            "rank": "species",
            "nomenclaturalCode": "botanical",
            "status": "variant",
            "genus": "Agoseris",
            "specificEpithet": "marshalii",
            "basionymKey": 13078
        }
    ],
    [
        {
            "id": "13122",
            "datasetKey": 15,
            "scientificName": "Troximon plebeium",
            "scientificNameID": "abc0007",
            "authorship": "Greene",
            "combinationAuthorship": {
              "authors": ["Greene"],
              "year": "1890"
            },
            "origin": "source",
            "rank": "species",
            "nomenclaturalCode": "botanical",
            "genus": "Troximon",
            "specificEpithet": "plebeium",
            "basionymKey": 13122
        },
        {
            "id": "13123",
            "datasetKey": 15,
            "scientificName": "Agoseris plebeia",
            "scientificNameID": "abc0008",
            "authorship": "(Greene) Greene",
            "basionymAuthorship": {
              "authors": ["Greene"]
            },
            "combinationAuthorship": {
              "authors": ["Greene"],
              "year": "1891"
            },
            "origin": "source",
            "rank": "species",
            "nomenclaturalCode": "botanical",
            "genus": "Agoseris",
            "specificEpithet": "plebeia",
            "basionymKey": 13122
        },
        {
            "id": "13124",
            "datasetKey": 15,
            "scientificName": "Agoseris grandiflora var. plebeia",
            "scientificNameID": "abc0009",
            "authorship": "(Greene) G. L. Wittr.",
            "basionymAuthorship": {
              "authors": ["Greene"]
            },
            "combinationAuthorship": {
              "authors": ["G. L. Wittr."],
              "year": "1928"
            },
            "origin": "source",
            "rank": "variety",
            "nomenclaturalCode": "botanical",
            "genus": "Agoseris",
            "specificEpithet": "grandiflora",
            "infraSpecificEpithet": "plebeia",
            "basionymKey": 13122
        }
    ]
]

application/json

Content: Name[][]

/dataset/{dkey}/taxon/{id}/verbatim


GET //dataset/{dkey}/taxon/{id}/verbatim HTTP/1.1
Host: api.col.plus

GET http://api.col.plus/dataset/{dkey}/taxon/{id}/verbatim

Retrieves the verbatim DarwinCore record of the taxon with the specified key,

Response 200


HTTP/1.1 200 OK
Date: Wednesday, November 7, 2018 4:02:17 PM CET
Content-Type: application/json

    {
    "key": 114621,
    "datasetKey": 24,
    "line": 4,
    "file": "AcceptedSpecies.txt",
    "type": "acef:AcceptedSpecies",
    "terms": {
        "acef:AuthorString": "Soepadmo",
        "acef:Family": "Fagaceae",
        "acef:AcceptedTaxonID": "Kew-114621",
        "acef:Phylum": "Tracheophyta",
        "acef:LTSDate": "Aug-2017",
        "acef:Sp2000NameStatus": "accepted name",
        "acef:LTSSpecialist": "Govaerts R.",
        "acef:HasModern": "1",
        "acef:SpeciesEpithet": "mariae",
        "acef:Kingdom": "Plantae",
        "acef:Order": "Fagales",
        "acef:Genus": "Lithocarpus",
        "acef:HasPreHolocene": "0",
        "acef:Class": "Magnoliopsida",
        "acef:IsExtinct": "0"
    },
    "issues": [
        "according to date invalid",
        "escaped characters"
    ]
}

application/json

Content: VerbatimRecord

/dataset/{dkey}/name


GET //dataset/{dkey}/name HTTP/1.1
Host: api.col.plus

GET http://api.col.plus/dataset/{dkey}/name

Paging parameters.

Parameters

Name Type Pattern Required Default Description
offset integer no

The requested number of offset records. Defaults to zero

limit integer no

The requested number of maximum records to be returned. Defaults to 10 and can be no more than 1000.

datasetKey string yes

The database key of the dataset

Response 200


HTTP/1.1 200 OK
Date: Wednesday, November 7, 2018 4:02:17 PM CET
Content-Type: application/json

application/json

Content: NameResultSet

/dataset/{dkey}/name/{id}


GET //dataset/{dkey}/name/{id} HTTP/1.1
Host: api.col.plus

GET http://api.col.plus/dataset/{dkey}/name/{id}

Retrieves the name with the specified id.

Parameters

Name Type Pattern Required Default Description
{id} string yes

name identifier as given by the source

Response 200


HTTP/1.1 200 OK
Date: Wednesday, November 7, 2018 4:02:17 PM CET
Content-Type: application/json

    {
    "id": "1000BA50801",
    "datasetKey": 1009,
    "scientificName": "Fomes obliquus",
    "rank": "species",
    "genus": "Fomes",
    "specificEpithet": "obliquus",
    "candidatus": false,
    "combinationAuthorship": {
        "authors": [
            "Cooke"
        ],
        "year": "1885"
    },
    "basionymAuthorship": {
        "authors": [
            "Pers."
        ],
        "exAuthors": [
            "Ach."
        ]
    },
    "origin": "source",
    "type": "scientific",
    "parsed": true,
    "authorship": "(Ach. ex Pers.) Cooke, 1885"
}

application/json

Content: Name

/dataset/{dkey}/name/{id}/synonyms


GET //dataset/{dkey}/name/{id}/synonyms HTTP/1.1
Host: api.col.plus

GET http://api.col.plus/dataset/{dkey}/name/{id}/synonyms

Retrieves all names in the same homotypic group as the name with the specified key.

Response 200


HTTP/1.1 200 OK
Date: Wednesday, November 7, 2018 4:02:17 PM CET
Content-Type: application/json

    [{
    "id": "1000BA50801",
    "datasetKey": 1009,
    "scientificName": "Fomes obliquus",
    "rank": "species",
    "genus": "Fomes",
    "specificEpithet": "obliquus",
    "candidatus": false,
    "combinationAuthorship": {
        "authors": [
            "Cooke"
        ],
        "year": "1885"
    },
    "basionymAuthorship": {
        "authors": [
            "Pers."
        ],
        "exAuthors": [
            "Ach."
        ]
    },
    "origin": "source",
    "type": "scientific",
    "parsed": true,
    "authorship": "(Ach. ex Pers.) Cooke, 1885"
}
,{
    "id": "1000BA50801",
    "datasetKey": 1009,
    "scientificName": "Fomes obliquus",
    "rank": "species",
    "genus": "Fomes",
    "specificEpithet": "obliquus",
    "candidatus": false,
    "combinationAuthorship": {
        "authors": [
            "Cooke"
        ],
        "year": "1885"
    },
    "basionymAuthorship": {
        "authors": [
            "Pers."
        ],
        "exAuthors": [
            "Ach."
        ]
    },
    "origin": "source",
    "type": "scientific",
    "parsed": true,
    "authorship": "(Ach. ex Pers.) Cooke, 1885"
}
]

application/json

Content: Name[]

/dataset/{dkey}/name/{id}/publishedIn


GET //dataset/{dkey}/name/{id}/publishedIn HTTP/1.1
Host: api.col.plus

GET http://api.col.plus/dataset/{dkey}/name/{id}/publishedIn

Retrieves the literature reference for the name with the specified key.

Response 200


HTTP/1.1 200 OK
Date: Wednesday, November 7, 2018 4:02:17 PM CET
Content-Type: application/json

    {
  "id": "432561",
  "datasetKey": 15,
  "csl": {
    "DOI":"10.1038/nrd842",
    "type":"article-journal",
    "author":[{"family":"Atkins","given":"Joshua H."},{"family":"Gershell","given":"Leland J."}],
    "title":"From the analyst's couch: Selective anticancer drugs",
    "container-title":"Nature Reviews Drug Discovery",
    "volume":"1",
    "issue":"7",
    "issued":{"date-parts":[[2002,7]]},
    "page":"491-492"
  }
}

application/json

Content: Reference

/dataset/{dkey}/name/{id}/relations


GET //dataset/{dkey}/name/{id}/relations HTTP/1.1
Host: api.col.plus

GET http://api.col.plus/dataset/{dkey}/name/{id}/relations

Retrieves nomenclatural relations for the name or its homotypical group

Parameters

Name Type Pattern Required Default Description
homotypic boolean yes

if true also includes all acts about related, homotypic names

Response 200


HTTP/1.1 200 OK
Date: Wednesday, November 7, 2018 4:02:17 PM CET
Content-Type: application/json

    [{
  "key": 721141,
  "datasetKey": 15,
  "type": "basionym",
  "nameId": "78612",
  "relatedNameId": "1655",
  "publishedInId": "786"
}
,{
  "key": 721141,
  "datasetKey": 15,
  "type": "basionym",
  "nameId": "78612",
  "relatedNameId": "1655",
  "publishedInId": "786"
}
]

application/json

Content: NameRelation[]

/dataset/{dkey}/name/{id}/verbatim


GET //dataset/{dkey}/name/{id}/verbatim HTTP/1.1
Host: api.col.plus

GET http://api.col.plus/dataset/{dkey}/name/{id}/verbatim

Retrieves the verbatim DarwinCore record of the name with the specified key,

Response 200


HTTP/1.1 200 OK
Date: Wednesday, November 7, 2018 4:02:17 PM CET
Content-Type: application/json

    {
    "key": 114621,
    "datasetKey": 24,
    "line": 4,
    "file": "AcceptedSpecies.txt",
    "type": "acef:AcceptedSpecies",
    "terms": {
        "acef:AuthorString": "Soepadmo",
        "acef:Family": "Fagaceae",
        "acef:AcceptedTaxonID": "Kew-114621",
        "acef:Phylum": "Tracheophyta",
        "acef:LTSDate": "Aug-2017",
        "acef:Sp2000NameStatus": "accepted name",
        "acef:LTSSpecialist": "Govaerts R.",
        "acef:HasModern": "1",
        "acef:SpeciesEpithet": "mariae",
        "acef:Kingdom": "Plantae",
        "acef:Order": "Fagales",
        "acef:Genus": "Lithocarpus",
        "acef:HasPreHolocene": "0",
        "acef:Class": "Magnoliopsida",
        "acef:IsExtinct": "0"
    },
    "issues": [
        "according to date invalid",
        "escaped characters"
    ]
}

application/json

Content: VerbatimRecord

/dataset/{dkey}/reference


GET //dataset/{dkey}/reference HTTP/1.1
Host: api.col.plus

GET http://api.col.plus/dataset/{dkey}/reference

Paging parameters.

Parameters

Name Type Pattern Required Default Description
offset integer no

The requested number of offset records. Defaults to zero

limit integer no

The requested number of maximum records to be returned. Defaults to 10 and can be no more than 1000.

datasetKey string yes

The database key of the dataset

Response 200


HTTP/1.1 200 OK
Date: Wednesday, November 7, 2018 4:02:17 PM CET
Content-Type: application/json

application/json

Content: ResultSet

/dataset/{dkey}/reference/{id}


GET //dataset/{dkey}/reference/{id} HTTP/1.1
Host: api.col.plus

GET http://api.col.plus/dataset/{dkey}/reference/{id}

get reference details by id

Parameters

Name Type Pattern Required Default Description
{id} string yes

reference id

Response 200


HTTP/1.1 200 OK
Date: Wednesday, November 7, 2018 4:02:17 PM CET
Content-Type: application/json

    {
  "id": "432561",
  "datasetKey": 15,
  "csl": {
    "DOI":"10.1038/nrd842",
    "type":"article-journal",
    "author":[{"family":"Atkins","given":"Joshua H."},{"family":"Gershell","given":"Leland J."}],
    "title":"From the analyst's couch: Selective anticancer drugs",
    "container-title":"Nature Reviews Drug Discovery",
    "volume":"1",
    "issue":"7",
    "issued":{"date-parts":[[2002,7]]},
    "page":"491-492"
  }
}

application/json

Content: Reference

/colsource


GET //colsource HTTP/1.1
Host: api.col.plus

GET http://api.col.plus/colsource

List of CoL sources. queryParameters: datasetKey: description: Filter by dataset responses: 200: body: application/json: type: ColSource[]

/decision


GET //decision HTTP/1.1
Host: api.col.plus

GET http://api.col.plus/decision

List of editorial decisions. queryParameters: datasetKey: description: Filter by dataset sectorKey: description: Filter by sector responses: 200: body: application/json: type: Decision[]

/sector


GET //sector HTTP/1.1
Host: api.col.plus

GET http://api.col.plus/sector

List of taxonomic sectors in the CoL. queryParameters: sourceKey: description: Filter by CoL source. responses: 200: body: application/json: type: Sector[]

/importer

/name/search


GET //name/search HTTP/1.1
Host: api.col.plus

GET http://api.col.plus/name/search

Executes a name search.

Parameters

Name Type Pattern Required Default Description
q string no

main query string

datasetKey integer no

dataset key

id string no

the name identifier

rank RankType domain, superkingdom, kingdom, subkingdom, infrakingdom, superphylum, phylum, subphylum, infraphylum, superclass, class, subclass, infraclass, parvclass, superlegion, legion, sublegion, infralegion, supercohort, cohort, subcohort, infracohort, magnorder, superorder, grandorder, order, suborder, infraorder, parvorder, superfamily, family, subfamily, infrafamily, supertribe, tribe, subtribe, infratribe, suprageneric name, genus, subgenus, infragenus, supersection, section, subsection, superseries, series, subseries, infrageneric name, species aggregate, species, infraspecific name, grex, subspecies, cultivar group, convariety, infrasubspecific name, proles, natio, aberration, morph, variety, subvariety, form, subform, pathovar, biovar, chemovar, morphovar, phagovar, serovar, chemoform, forma specialis, cultivar, strain, other, unranked no

filter by rank

nomstatus NomenclaturalStatusType ok, unavailable, illegitimate, variant, conserved, rejected, doubtful, unevaluated no

filter by nomenclatural status

status TaxonomicStatusType accepted, doubtful no

filter by taxonomic status

issue string no

filter by issue found

type NameType scientific, virus, hybrid-formula, cultivar, otu, placeholder, none no

filter by name type

publishedIn string no

publishedIn reference id to filter names by

hasField string no

filter that only includes name where the requested name property is not null

facet enum dataset_key, rank, nom_status, status, issue, type, field no

request a facet to be returned. The facet limit defaults to 50

sortBy enum relevance, name, key no

sort order

offset integer no

The requested number of offset records. Defaults to zero

limit integer no

The requested number of maximum records to be returned. Defaults to 10 and can be no more than 1000.

Response 200


HTTP/1.1 200 OK
Date: Wednesday, November 7, 2018 4:02:17 PM CET
Content-Type: application/json

    {
    "offset": 0,
    "limit": 10,
    "total": 179025,
    "result": [
        {
            "id": "2157461",
            "datasetKey": 101,
            "scientificName": "Aagaardia",
            "rank": "genus",
            "uninomial": "Aagaardia",
            "candidatus": false,
            "origin": "denormed_classification",
            "type": "scientific",
            "acceptedName": true,
            "taxa": [
                {
                    "id": "1123278",
                    "status": "accepted"
                }
            ],
            "parsed": true
        },
        {
            "id": "Sys-172336",
            "datasetKey": 101,
            "scientificName": "Aagaardia longicalcis",
            "rank": "species",
            "genus": "Aagaardia",
            "specificEpithet": "longicalcis",
            "candidatus": false,
            "combinationAuthorship": {
                "authors": [
                    "Saether"
                ],
                "year": "2000"
            },
            "origin": "source",
            "type": "scientific",
            "acceptedName": true,
            "taxa": [
                {
                    "id": "Sys-172336",
                    "status": "ACCEPTED"
                }
            ],
            "parsed": true,
            "authorship": "Saether, 2000"
        },
        {
            "id": "Sys-196835",
            "datasetKey": 101,
            "scientificName": "Aagaardia oksanae",
            "rank": "species",
            "genus": "Aagaardia",
            "specificEpithet": "oksanae",
            "candidatus": false,
            "combinationAuthorship": {
                "authors": [
                    "Makarchenko"
                ],
                "year": "2005"
            },
            "origin": "source",
            "type": "scientific",
            "acceptedName": true,
            "taxa": [
                {
                    "id": "Sys-196835",
                    "status": "ACCEPTED"
                }
            ],
            "parsed": true,
            "authorship": "Makarchenko, 2005"
        },
        {
            "id": "Sys-172334",
            "datasetKey": 101,
            "scientificName": "Aagaardia protensa",
            "rank": "species",
            "genus": "Aagaardia",
            "specificEpithet": "protensa",
            "candidatus": false,
            "combinationAuthorship": {
                "authors": [
                    "Saether"
                ],
                "year": "2000"
            },
            "origin": "source",
            "type": "scientific",
            "acceptedName": true,
            "taxa": [
                {
                    "id": "Sys-172334",
                    "status": "ACCEPTED"
                }
            ],
            "parsed": true,
            "authorship": "Saether, 2000"
        },
        {
            "id": "Sys-87526",
            "datasetKey": 101,
            "scientificName": "Aagaardia sivertseni",
            "rank": "species",
            "genus": "Aagaardia",
            "specificEpithet": "sivertseni",
            "candidatus": false,
            "basionymAuthorship": {
                "authors": [
                    "Aagaard"
                ],
                "year": "1979"
            },
            "origin": "source",
            "type": "scientific",
            "acceptedName": true,
            "taxa": [
                {
                    "id": "Sys-87526",
                    "status": "accepted"
                }
            ],
            "parsed": true,
            "authorship": "(Aagaard, 1979) "
        },
        {
            "id": "Sys-172335",
            "datasetKey": 101,
            "scientificName": "Aagaardia triangulata",
            "rank": "species",
            "genus": "Aagaardia",
            "specificEpithet": "triangulata",
            "candidatus": false,
            "combinationAuthorship": {
                "authors": [
                    "Saether"
                ],
                "year": "2000"
            },
            "origin": "source",
            "type": "scientific",
            "acceptedName": true,
            "taxa": [
                {
                    "id": "Sys-172335",
                    "status": "ACCEPTED"
                }
            ],
            "parsed": true,
            "authorship": "Saether, 2000"
        },
        {
            "id": "2165044",
            "datasetKey": 101,
            "scientificName": "Abago",
            "rank": "genus",
            "uninomial": "Abago",
            "candidatus": false,
            "origin": "denormed_classification",
            "type": "scientific",
            "acceptedName": true,
            "taxa": [
                {
                    "id": "1114398",
                    "status": "ACCEPTED"
                }
            ],
            "parsed": true
        },
        {
            "id": "Sys-152428",
            "datasetKey": 101,
            "scientificName": "Abago rohdendorfi",
            "rank": "species",
            "genus": "Abago",
            "specificEpithet": "rohdendorfi",
            "candidatus": false,
            "combinationAuthorship": {
                "authors": [
                    "Grunin"
                ],
                "year": "1966"
            },
            "origin": "source",
            "type": "scientific",
            "acceptedName": true,
            "taxa": [
                {
                    "id": "Sys-152428",
                    "status": "ACCEPTED"
                }
            ],
            "parsed": true,
            "authorship": "Grunin, 1966"
        },
        {
            "id": "2159955",
            "datasetKey": 101,
            "scientificName": "Abaristophora",
            "rank": "genus",
            "uninomial": "Abaristophora",
            "candidatus": false,
            "origin": "denormed_classification",
            "type": "scientific",
            "acceptedName": true,
            "taxa": [
                {
                    "id": "1231163",
                    "status": "ACCEPTED"
                }
            ],
            "parsed": true
        },
        {
            "id": "Sys-16345",
            "datasetKey": 101,
            "scientificName": "Abaristophora arctophila",
            "rank": "species",
            "genus": "Abaristophora",
            "specificEpithet": "arctophila",
            "candidatus": false,
            "combinationAuthorship": {
                "authors": [
                    "Schmitz"
                ],
                "year": "1927"
            },
            "origin": "source",
            "type": "scientific",
            "acceptedName": true,
            "taxa": [
                {
                    "id": "Sys-16345",
                    "status": "ACCEPTED"
                }
            ],
            "parsed": true,
            "authorship": "Schmitz, 1927"
        }
    ],
    "last": false
}

application/json

Content: NameSearchResultSet

/name/matching


GET //name/matching HTTP/1.1
Host: api.col.plus

GET http://api.col.plus/name/matching

Match name against the name index. Eventually should be exposed in public API.

Parameters

Name Type Pattern Required Default Description
q string yes

scientific name to match

rank RankType domain, superkingdom, kingdom, subkingdom, infrakingdom, superphylum, phylum, subphylum, infraphylum, superclass, class, subclass, infraclass, parvclass, superlegion, legion, sublegion, infralegion, supercohort, cohort, subcohort, infracohort, magnorder, superorder, grandorder, order, suborder, infraorder, parvorder, superfamily, family, subfamily, infrafamily, supertribe, tribe, subtribe, infratribe, suprageneric name, genus, subgenus, infragenus, supersection, section, subsection, superseries, series, subseries, infrageneric name, species aggregate, species, infraspecific name, grex, subspecies, cultivar group, convariety, infrasubspecific name, proles, natio, aberration, morph, variety, subvariety, form, subform, pathovar, biovar, chemovar, morphovar, phagovar, serovar, chemoform, forma specialis, cultivar, strain, other, unranked no

rank to restrict matches to

code NomCodeType bacterial, botanical, cultivated, viral, zoological, unknown no

nomenclatural code to restrict matches to

trusted boolean yes false

if true unmatched name will be inserted into the names index

verbose boolean yes false

if verbose list alternatively considered name matches

Response 200


HTTP/1.1 200 OK
Date: Wednesday, November 7, 2018 4:02:17 PM CET
Content-Type: application/json

application/json

Content: NameMatch

/parser

/parser/name


GET //parser/name HTTP/1.1
Host: api.col.plus

GET http://api.col.plus/parser/name

List parsed names.

Parameters

Name Type Pattern Required Default Description
name string yes

The names to parse (may occur multiple times)

Response 200


HTTP/1.1 200 OK
Date: Wednesday, November 7, 2018 4:02:17 PM CET
Content-Type: application/json

    [{
    "id": "1000BA50801",
    "datasetKey": 1009,
    "scientificName": "Fomes obliquus",
    "rank": "species",
    "genus": "Fomes",
    "specificEpithet": "obliquus",
    "candidatus": false,
    "combinationAuthorship": {
        "authors": [
            "Cooke"
        ],
        "year": "1885"
    },
    "basionymAuthorship": {
        "authors": [
            "Pers."
        ],
        "exAuthors": [
            "Ach."
        ]
    },
    "origin": "source",
    "type": "scientific",
    "parsed": true,
    "authorship": "(Ach. ex Pers.) Cooke, 1885"
}
,{
    "id": "1000BA50801",
    "datasetKey": 1009,
    "scientificName": "Fomes obliquus",
    "rank": "species",
    "genus": "Fomes",
    "specificEpithet": "obliquus",
    "candidatus": false,
    "combinationAuthorship": {
        "authors": [
            "Cooke"
        ],
        "year": "1885"
    },
    "basionymAuthorship": {
        "authors": [
            "Pers."
        ],
        "exAuthors": [
            "Ach."
        ]
    },
    "origin": "source",
    "type": "scientific",
    "parsed": true,
    "authorship": "(Ach. ex Pers.) Cooke, 1885"
}
]

application/json

Content: Name[]


POST //parser/name HTTP/1.1
Host: api.col.plus
Content-Type: application/json

POST http://api.col.plus/parser/name

List parsed names. The names to be parsed can be specified as a JSON array in the request body; a file upload with one name per line, or as plain/text content in the request body.

Body

application/json

Content: any

multipart/form-data

Content: any

text/plain

Content: any

Response 200


HTTP/1.1 200 OK
Date: Wednesday, November 7, 2018 4:02:17 PM CET
Content-Type: application/json

    [{
    "id": "1000BA50801",
    "datasetKey": 1009,
    "scientificName": "Fomes obliquus",
    "rank": "species",
    "genus": "Fomes",
    "specificEpithet": "obliquus",
    "candidatus": false,
    "combinationAuthorship": {
        "authors": [
            "Cooke"
        ],
        "year": "1885"
    },
    "basionymAuthorship": {
        "authors": [
            "Pers."
        ],
        "exAuthors": [
            "Ach."
        ]
    },
    "origin": "source",
    "type": "scientific",
    "parsed": true,
    "authorship": "(Ach. ex Pers.) Cooke, 1885"
}
,{
    "id": "1000BA50801",
    "datasetKey": 1009,
    "scientificName": "Fomes obliquus",
    "rank": "species",
    "genus": "Fomes",
    "specificEpithet": "obliquus",
    "candidatus": false,
    "combinationAuthorship": {
        "authors": [
            "Cooke"
        ],
        "year": "1885"
    },
    "basionymAuthorship": {
        "authors": [
            "Pers."
        ],
        "exAuthors": [
            "Ach."
        ]
    },
    "origin": "source",
    "type": "scientific",
    "parsed": true,
    "authorship": "(Ach. ex Pers.) Cooke, 1885"
}
]

application/json

Content: Name[]

/vocab


GET //vocab HTTP/1.1
Host: api.col.plus

GET http://api.col.plus/vocab

List of all available vocabularies by their unique lowercase form. Any of the names can be used as valid subresources to list the actual enumeration values.

Response 200


HTTP/1.1 200 OK
Date: Wednesday, November 7, 2018 4:02:17 PM CET
Content-Type: application/json

    ["continent","country","areastandard","cslreftype","nametype","origin","language","frequency","rank","nomacttype","coverage","nomstatus","dataformat","importstate","issue","gazetteer","cslvariable","typestatus","lifezone","distributionstatus","taxonomicstatus","kingdom","datasettype","license","nomcode","namepart"]

application/json

Content: string[]

/vocab/{name}


GET //vocab/{name} HTTP/1.1
Host: api.col.plus

GET http://api.col.plus/vocab/{name}

List of all enumeration values for the requested vocabulary.

Response 200


HTTP/1.1 200 OK
Date: Wednesday, November 7, 2018 4:02:17 PM CET
Content-Type: application/json

    ["domain","superkingdom","kingdom","subkingdom","infrakingdom","superphylum","phylum","subphylum","infraphylum","superclass","class","subclass","infraclass","parvclass","superlegion","legion","sublegion","infralegion","supercohort","cohort","subcohort","infracohort","magnorder","superorder","grandorder","order","suborder","infraorder","parvorder","superfamily","family","subfamily","infrafamily","supertribe","tribe","subtribe","infratribe","suprageneric name","genus","subgenus","infragenus","supersection","section","subsection","superseries","series","subseries","infrageneric name","species aggregate","species","infraspecific name","grex","subspecies","cultivar group","convariety","infrasubspecific name","proles","natio","aberration","morph","variety","subvariety","form","subform","pathovar","biovar","chemovar","morphovar","phagovar","serovar","chemoform","forma specialis","cultivar","strain","other","unranked"]

application/json

Content: string[]

    Examples