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 current version of the taxonomy.

Input parameters

None

Ouput parameters

• weburl : (string) The release page for this version of the taxonomy
• author : (string) The author string
• name : (string) The name of the taxonomy
• source : (string) The full identifying information for this version of the taxonomy
• version : (string) The version number of the taxonomy

Example command:

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

Example result:

{
	"weburl" : "https://tree.opentreeoflife.org/about/taxonomy-version/ott2.9",
  "author" : "open tree of life project",
  "name" : "ott",
  "source" : "ott2.9draft12",
  "version" : "2.9"
}

taxon_info

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

POST    /taxonomy/taxon_info

Get information about a known taxon in the taxonomy.

Input parameters

Parameters with bold type definitions are required.

• ott_id : (integer) An OTT id for the taxon of interest. (Ordinarily a taxon has only one OTT id, but occasionally it has a primary id and one or more aliases.)
• source_id : (string) A source taxonomy id for the taxon of interest, in the form prefix:id, for example ncbi:9443, irmng:11338. Valid prefixes are currently ncbi, gbif, worms, if, and irmng. Either ott_id or source_id must be given, but not both.
• include_children : (boolean) Whether or not to include information about all the children of this taxon. By default, this option is set to false.
• include_lineage : (boolean) Whether or not to include information about all the higher level taxa that include this taxon. By default, this option is set to false.
• include_terminal_descendants : (boolean) Provide a list of terminal OTT ids contained by this taxon.

Output parameters

• ott_id : (integer) The primary OTT id of the taxon of interest. Usually this will be the same as the ott_id input parameter, but if the input OTT id is an alias, the returned OTT id is the primary id for the taxon.
• name : (string) The taxon name
• rank : (string) Taxonomic rank
• tax_sources : (list of strings) an ordered list of identifiers for taxonomic sources, such as other taxonomies, that define taxa judged equivalent to this taxon. Each string in the list has a CURIEorIRI syntax, so this field might hold [“ncbi:9242”, “h2007:”, “http://dx.doi.org/10.9779/azhjj0”], for example.
• unique_name : (string) The unique name for the taxon; often equivalent to name
• flags : (list of strings) An array containing the OpenTree flags that pertain to this taxon. See the taxonomy documentation for more information about flags.
• synonyms : (list of strings) The list of names judged to be synonyms of this taxon.
• is_suppressed : (boolean) Whether or not the taxon is suppressed from TNRS results
• lineage : (list of dict) All of the higher level taxa that include this taxon, with the least inclusive taxa at lower indices (i.e. higher indices are higher taxa). Each item is the list is an extended-taxon-descriptor.
• children : (list of dict) An array of the immediate children of this taxon. Each item is the list is an extended-taxon-descriptor.
• terminal_descendants : (list of long) An array with one OTT id for each terminal descendant of 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:

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

mrca

Given a set of OTT ids, get the taxon that is the most recent common ancestor (the MRCA) of all the identified taxa.

POST    /taxonomy/mrca

Return information about the most recent common ancestral taxon (the MRCA) of the identified taxa. 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'.

Yields 400 if any of the ott_ids does not designate a taxon

Input parameters

Parameters with bold type definitions are required.

• ott_ids : (list of long) The OTT ids (in an array) for the taxa whose MRCA is to be found.

Output parameters

• mrca : (dict) An extended-taxon-descriptor with information about the MRCA taxon

Example command:

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

Example result:

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

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.

Yields 400 if any of the OTT ids does not designate a taxon

Input parameters

Parameters with bold type definitions are required.

• ott_id : (integer) The OTT id of the taxon of interest.
• label_format : (string) The format for the labels. If provided, this must be one of "name", "id", or "name_and_id", indicating whether the node labels should contain (respectively) just the cleaned name (i.e. with punctuation and whitespace replaced with underscores), just the OTT id, or the cleaned name plus the OTT id (default).

Output parameters

• newick : (string) The newick string that describes the taxonomy subtree

Example command:

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

Example result:

{
  "newick" : "(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;"
}