Taxonomy API v3

Methods for accessing information about the current Open Tree of Life taxonomy. These methods require Open Tree of Life Taxonomy identifiers (ott ids), which can be determined using the tnrs to match against taxon names.

The base URL for all services:

https://api.opentreeoflife.org/v3/

This page is part of the Open Tree of Life Web APIs.

URL	Verb	Summary
/taxonomy/about	POST	Return information about the taxonomy, including version.
/taxonomy/mrca	POST	Given a set of ott ids, get the taxon that is the most recent common ancestor (the MRCA) of all the identified taxa.
/taxonomy/subtree	POST	Given an ott id, return complete taxonomy subtree descended from specified taxon.
/taxonomy/taxon_info	POST	Given an ott id, return information about the specified taxon.

about (taxonomy)

Return information about the taxonomy, including version.

POST    /taxonomy/about

Return metadata and information about the taxonomy itself. Currently the available metadata is fairly sparse, but includes (at least) the version, and the location from which the complete taxonomy source files can be downloaded.

Parameters:

Parameters with bold type definitions are required.

Example command:

$ curl -X POST https://api.opentreeoflife.org/v3/taxonomy/about

Example result:

{
  "weburl" : "https://github.com/OpenTreeOfLife/opentree/wiki/Open-Tree-Taxonomy",
  "author" : "open tree of life project",
  "source" : "ott2.9draft12"
}

lica

Given a set of ott ids, get the taxon that is the least inclusive common ancestor (the LICA) of all the identified taxa.

POST    /taxonomy/lica

Return information about the least inclusive common ancestral taxon (the LICA) of the identified taxa. A taxonomic LICA is analogous to a most recent common ancestor (MRCA) in a phylogenetic tree. For example, the LICA for the taxa 'Pan' and 'Lemur' in the taxonomy represented by the newick string '(((Pan,Homo,Gorilla)Hominidae,Gibbon)Hominoidea,Lemur)Primates' is 'Primates'.

Parameters:

Parameters with bold type definitions are required.

ott_ids : longs
The ott ids (in an array) for the taxa whose LICA is to be found.

include_lineage : boolean
Whether or not to include information about the higher level taxa that include the identified LICA. By default, this option is set to false. If it is set to true, the lineage will be provided in an ordered array, with the least inclusive taxa at lower indices (i.e. higher indices are higher taxa).

Example command:

$ curl -X POST https://api.opentreeoflife.org/v3/taxonomy/lica \
-H 'content-type:application/json' -d \
'{"ott_ids":[515698,590452,409712,643717]}'

Example result:

{
  "lica" : {
    "tax_sources" : [ "ncbi:4209", "worms:234044", "gbif:414", "irmng:10011" ],
    "unique_name" : "",
    "ott_id" : 1042120,
    "synonyms" : [ "Asterales" ],
    "flags" : [ ],
    "rank" : "order",
    "name" : "Asterales",
  },
  "ott_ids_not_found" : [ 409712 ]
}

v2 to v3 renamings: ot:ottId to ott_id, maybe rank to tax_rank, maybe ot:ottTaxonName to name or tax_name (but not flags to tax_flags ... ?)

node_id removed (was taxomachine neo4j node id, unrelated to treemachine neo4j node id)

subtree (taxonomy)

Given an ott id, return complete taxonomy subtree descended from specified taxon.

POST    /taxonomy/subtree

Extract and return the inclusive taxonomic subtree i.e. (a subset of the taxonomy) below a given taxon. The taxonomy subtree is returned in newick format.

Parameters:

Parameters with bold type definitions are required.

ott_id : long
The OTT id of the taxon of interest.

label_format : string
The format for the labels. If provided, this must be one of the options: ["name", "id", "name_and_id","original_name"], indicating whether the node labels should contain (respecitvely) just the cleaned name (i.e. with punctuation and whitespace replaced with underscores), just the ott id, the cleaned name and as well as the ott id (default), or the original name without punctuation removed.

Example command:

$ curl -X POST https://api.opentreeoflife.org/v3/taxonomy/subtree \
-H 'Content-type:application/json' -d '{"ott_id":515698}'

Example result:

{
  "subtree" : "(Barnadesia_sp._1151_ott825484,Barnadesia_caryophylla_ott515696,Barnadesia_parviflora_ott503064,Barnadesia_odorata_ott503066,Barnadesia_glomerata_ott503056,Barnadesia_dombeyana_ott503058,(Barnadesia_lehmannii_var._lehmannii_ott1084324,Barnadesia_lehmannii_var._villosa_ott1084322)Barnadesia_lehmannii_ott503060,Barnadesia_jelskii_ott503062,Barnadesia_arborea_ott503052,Barnadesia_pycnophylla_ott503043,Barnadesia_polyacantha_ott503045,Barnadesia_sp._Palmer_180_ott124782,Barnadesia_spinosa_ott13308)Barnadesia_ott515698;"
}

taxon

Given an ott id, return information about the specified taxon.

POST    /taxonomy/taxon_info

Get information about a known taxon in the taxonomy.

Parameters:

Parameters with bold type definitions are required.

ott_id : long
The OTT id of the taxon of interest.

include_children : boolean
Whether or not to include information about all the children of this taxon. By default, this option is set to false. If it is set to true, the children will be provided in an array.

include_lineage : boolean
Whether or not to include information about all the higher level taxa that include this one. By default, this option is set to false. If it is set to true, the lineage will be provided in an ordered array, with the least inclusive taxa at lower indices (i.e. higher indices are higher taxa).

list_terminal_descendants : boolean
Provide a list of terminal OTT ids contained by this taxon.

Example command:

$ curl -X POST https://api.opentreeoflife.org/v3/taxonomy/taxon_info \
-H 'content-type:application/json' -d '{"ott_id":515698}'

Example result:

{
  "tax_sources" : [ "ncbi:4237", "gbif:3105285", "irmng:1046392" ],
  "unique_name" : "",
  "ott_id" : 515698,
  "synonyms" : [ "Barnadesia", "Barnadesia Mutis" ],
  "flags" : [ ],
  "rank" : "genus",
  "name" : "Barnadesia",
}