OneZoom tree APIs

These APIs allow you to access data used to populate the OneZoom tree.

Overview

Several mappings used by the OneZoom Tree of Life Explorer may be useful for other purposes, and are made available via public APIs. These APIs all require an OTT ID to be passed in (e.g. the OTT ID for Homo sapiens is 770315, for mammals it is 244265). You can obtain OTT IDs for scientific names through the Open Tree of Life TNRS service.

Note that APIs only return results that are on the OneZoom Tree of Life. For example, we do not normally include subspecies, such as Canis lupus familiaris (the domestic dog) on the OneZoom tree: only the full species, Canis lupus (the grey wolf, including the domestic dog, dingo, Indian wolf, etc.), are displayed on the tree and returned using from OneZoom APIs. Although there is an Open Tree identifier for Canis lupus familiaris, it will not be recognised if passed to this API. Additionally, OneZoom does not store higher level names for monospecific taxa, i.e. for a species like the tuatara, Sphenodon punctatus, the OTT for the species (35890) will be recognised, but searching for the genus Sphenodon (OTT 35886) will not return any results, nor will the higher level monospecific order Rhynchocephalia (OTT 35876). In a similar vein, where multiple taxonomic names describe the same set of species on the OneZoom tree, only the highest distinguishing level is used. For example, lancelets are classified in OneZoom as Cephalochordata (OTT 176555): the lower level family Branchiostomidae (OTT 176551), in which all living cephalochordates also fall, is not recognised in OneZoom or in this API.

Services available

Public APIs are available which, for a given set of Open Tree Taxonomy (OTT) identifiers, return:

  • the best matching vernacular (common) names in a given language
  • a set of identifiers in different online databases, such as Wikidata, the Encyclopedia of Life, or the IUCN Red List
  • a set of up to 8 representative images for higher level taxa
  • a phylogenetically informed popularity index for all taxa, which is documented on a separate page
API services are accessed via URLs that return JSON data for any set of passed-in Open Tree Taxonomy identifiers (you cannot pass in scientific names). Services generally require you to specify an API key (e.g. by appending key=MY_API_KEY to the URL) this allows us to keep track of the volume of requests we get from different private users: no other information is stored. If you have not been given an API key, you can use the public key (0), which is restricted to 5 taxa per request.

Please remember to cite OneZoom if you use this API in your own project or publication. Use of the OneZoom APIs is subject to our terms of use.

URL: API/otts2vns

An API to get a best hit vernacular (common) name for an OTT , e.g. https://www.onezoom.org/API/otts2vns?key=0&otts=770315,244265,542509.

Parameters

Required
key
Your OneZoom API key (use the public key 0 if you have not been given one)
otts
A comma-separated list of Open Tree Taxonomy identifiers (one or more positive integers)
Optional
lang
A language code to specify which language to use. This can be a 2 or 3 letter code such as en or fr, or a more specific regional code such as en-gb (British English) or zh-hant (Chinese, in traditional script). If not given, assume en
all
If 1 or any truthy value, instead of returning a single best name for each OTT, return an array of names for each OTT, in decreasing order of preference.
include_unpreferred
If 1 or any truthy value, and a single name is requested for each OTT (i.e. all is not set), then if there is no name marked as preferred in this language, consider returning a name marked as unpreferred (i.e. less likely to be correct).
nulls
If 1 or any truthy value, and there is no vernacular in the specified language, return a null value for this OTT in the returned JSON object, otherwise the OTT ID will be absent from the returned object

Return values

In the absence of error, the returned JSON object contains the following properties:
lang
The lang string originally used in the request.
OTT ids ...
Each OTT ID passed in will create a JSON property whose name is the OTT ID and value is a string (or array of strings, if all is specified). Unicode characters are represented as e.g. "\u5c0f"

Test this API

  • (244265 is mammals, 542509 is Mus musculus, the house mouse)

URL: API/otts2identifiers

An API to get identifiers in other databases such as Wikidata and the Encyclopedia of Life, e.g. https://www.onezoom.org/API/otts2identifiers?key=0&otts=770315,244265,542509.

Currently identifiers are returned for all taxa from the following databases: ['ott', 'ncbi', 'ifung', 'worms', 'irmng', 'gbif', 'ipni', 'eol', 'wikidata'], with leaf node taxa having additional identifiers for ['iucn']. Note that some popular species such as humans have both an official taxonomic Wikidata entry and a common name entry (which tends to contain the links to different language wikipedias). In this case we tend to return the common name entry (unless it has no english language wikipedia link).

Parameters

Required
key
Your OneZoom API key (use the public key 0 if you have not been given one)
otts
A comma-separated list of Open Tree Taxonomy identifiers (one or more positive integers)

Return values

In the absence of error, the returned JSON object contains the following properties:
headers
So as to avoid repeating the same properties for each OTT returned, the headers object provides an integer index into each item returned in the ids object. For example, given a returned object ret the Wikidata Q-ID of humans (OTT 770315) can be accessed using 
ret.ids["770315"][ret.headers.wikidata]
ids
This property contains JSON object listing identifiers. Each name in the object is an OTT ID, with a corresponding value being an array of data. The order of the values corresponds to the headers provided above.

Test this API

  • (244265 is mammals, 542509 is Mus musculus, the house mouse)

URL: API/node_images

An API to get reusable, phylogenetically diverse and representative images for higher taxa. Images are either Creative Commons Attribution only, Creative Commons Share-Alike, or public domain. Each taxon can return URLs to up to 8 square thumbnail images, along with their copyright and licensing information, and a quality score, e.g. https://www.onezoom.org/API/node_images?key=0&otts=244265,361838

Parameters

Required
key
Your OneZoom API key (use the public key 0 if you have not been given one)
otts
A comma-separated list of Open Tree Taxonomy identifiers (one or more positive integers)
Optional
type
Either any, verified or pd, specifying whether to return any representative images, only images that have been verified as correctly identified, or only public domain images. If not given, assume any.

Return values

In the absence of error, the returned JSON object contains the following properties:
taxa
A map of input OTT ids to an object containing properties name (the scientific name of the input OTT, if it has one) and otts (an array of up to 8 OTTs of species that have "representative" images available).
headers
So as to avoid repeating the same properties for each image returned, the headers object provides an integer index into each item returned in the images object. For example, given a returned object r the URLs of the first 3 images used to represent mammals (OTT 244265) can be accessed using 
r.images[r.taxa["244265"].otts[0]][r.headers.url]
r.images[r.taxa["244265"].otts[1]][r.headers.url]
r.images[r.taxa["244265"].otts[2]][r.headers.url]
The headers for each image include name (scientific name), url, rights (the copyright holder), licence (e.g. CC-BY 2.0 (http://creativecommons.org/licenses/by/2.0/)) and rating (an image rating, from 0..50000).
images
The list of images, keyed by the OTT ID of the pictured species
type
The type of images (any, verified or pd) requested.

Test this API

  • (244265 is mammals, 361838 is green plants

URL: API/getOTT

An API to get the corresponding Open Tree IDs for a variety of identifiers

Parameters

Optional
eol
Find corresponding OTTs for EoL ids (to specify multiple IDs, include the parameter multiple times).
gbif
Find corresponding OTTs for GBIF ids (to specify multiple IDs, include the parameter multiple times).
ncbi
Find corresponding OTTs for NCBI ids (to specify multiple IDs, include the parameter multiple times).
iucn
Find corresponding OTTs for IUCN ids (to specify multiple IDs, include the parameter multiple times).

Return values

In the absence of error, the returned JSON object contains the following properties:
eol
A map of input EoL ids to OTT ids.
gbif
A map of input GBIF ids to OTT ids.
ncbi
A map of input NCBI ids to OTT ids.
iucn
A map of input IUCN ids to OTT ids.

Test this API