Tree of Life Web Services: Downloading the ToL Tree Structure
Downloading a ToL branch is a two-step process:
- Find the unique ToL identifier for the root node of the branch you want to download:
- Use the ToL Group ID Service, which returns information about group names and identifiers.
- Use the ToL Tree Structure Service, which returns the tree structure along with group names and properties of groups.
Group ID Service
The Group ID Service url is:
where xxx is the name of the group for which you want to retrieve the unique ToL identifier.
The Group ID Service takes a single string query parameter, group, which is the name of the group which you want to locate in the ToL database. For example, if you want to find the groups in the ToL that match the name Bembidion, the complete url is:
The group parameter will be matched to names attached to nodes in the ToL database. Matches can be made either with "official ToL node names" (usually valid scientific names) or "other ToL names" (e. g., synonyms, English names, names indicating different taxonomic ranks).
The response is an XML document, with a single NODES element wrapping one or more NODE elements. The NODES element has a single numeric attribute, COUNT, which indicates the number of NODE elements contained in the response file. Each NODE element has a single numeric attribute, ID, which is the node's unique id in the ToL. The NODE element will also contain a NAME element, which is the node's "official" name in the ToL database.
If the group parameter can be matched exactly, the service will return only those exact matches. If only partial matches can be made, all partial matches will be returned. For example, a search for Bembidion, will result in a single perfect match with name for the genus Bembidion, so only one NODE element will be returned; while a search for Bembidi will return multiple NODE elements for partial matches, e. g., for the genus Bembidion, the species of Bembidion, Bembidiina, Bembidiini, etc.
If there is more than one match to a query, NODE elements will also contain a PARENTGROUP element which provides the name of the group's parent group in the ToL. If there are no matches to a query, there is a single ERROR element that contains text explaining the cause of the error.
Tree Structure Service
The tree structure service url is
where yyy is the unique identifier for a group in the ToL database.
Most users of the tree structure service need only concern themselves with a single numeric parameter, node_id, which is the unique identifier for a group in the ToL database. In order to download the structure for the entire tree use node_id=1, which is the node id for Life on Earth. The ids of other named nodes may be obtained via the ToL Group ID Service (see above). If a named node also has a ToL branch or leaf page attached to it, you can also get its id from the page url. In ToL page urls, the node id will usually be appended at then end, separated by a slash from the group name. For example, the url for the Bembidion page is:
and the id for the Bembidion node is 194.
There is another parameter, optype that can be used to render the output into a different format. Currently a value of 0 (the default) outputs the tree according to the proprietary ToL Response Format. A value of 1 will output the tree in TreeML, a format used for Graph visualization programs.
ToL Response Format
The structure of the tree is contained in a single XML element, the <TREE> element. The <TREE> element contains a single element, <NODE>, which contains zero or more <NODES> elements. This pattern repeats itself out to the tips of the current tree structure of the ToL web project. While the current tree structure is by no means complete, it does extend the actual leaves of the tree (species, subspecies, populations, or strains) in some branches. This is denoted by a special LEAF attribute on NODE elements. Below is a summary of other elements and attributes that are included in the XML file.
NODE Elements Summary
|NAME||The official name for the node in the Tree of Life Web Project. Usually, but not always, the valid scientific name for the group.|
|DESCRIPTION||Brief description of the group.|
|AUTHORITY||Authors for a given name.|
|NAMECOMMENT||Additional comments about the node name|
|COMBINATION_AUTHOR||Names of authors of a new combination.|
|AUTHDATE||Publication date of the node name.|
|OTHERNAMES||Element nesting other names that are applied to the entire group represented by the current node.|
|OTHERNAME||Another names for the entire group, e. g., synonyms, English names, names in other languages, names indicating different taxonomic ranks.|
|COMMENTS||Comments about another name.|
|NODES||Children nodes for the current node.|
NODE Attributes Summary
|ID||The unique identifier for the node on the Tree of Life Web Project|
placement in the tree structure:
|COMBINATION_DATE||Publication date of the new combination|
|CHILDCOUNT||Number of descendent nodes.|
OTHERNAME Attributes Summary
|SEQUENCE||Position of the current name in the other names sequence. Determines the sequence in which names are printed on ToL pages.|
|DATE||Publication date of the other name.|
Note that the ToL tree structure is still far from complete. Many important groups are missing, and not all branches have undergone expert review. Our ideas about the phylogenetic relationships of organisms are constantly evolving, as more data become available and new analyses are published. The ToL structure will thus be subject to continuous revision and expansion. In its current, incomplete state, the phylogenetic information compiled by ToL contributors is valuable as a preliminary, synthetic estimate of the relationships among a large subset of known organisms.
The downloadable version of the ToL tree structure is licensed under the Attribution Creative Commons License. This license applies only to the downloadable XML files containing the ToL tree structure. For the terms and conditions of use of other ToL materials, please refer to the page about Tree of Life Copyright Policies.
Resources permitting, we will soon make additional ToL project data available for public use. In particular, we are planning to develop web services for the distribution of images and other media files that we have collected for all the different groups of organisms in the Tree of Life. An increasing number of our media files are released under creative commons licenses or in the public domain. The ToL media web services will allow people to download media files attached to nodes in a given branch of the Tree of Life (e.g., all birds, all penguins, all Spheniscus species) based on license type and potentially a variety of other criteria.
Old Tree Structure XML File
Some of you might still want to use our old, static XML file containing the structure of the entire tree:ToL Tree Structure XML File ToL Tree Structure XML File (zipped version)
This file is currently not up-to-date and we are working getting this back to being current. Until this is stated as being current again, please consider this data stale.