Tree of Life Web Services: Downloading the ToL Tree Structure

The tree structure of the Tree of Life web project is available to the public for re-use in other projects. You can download either the entire tree or particular branches. Before using this service, please see the Disclaimer and Terms of Use.

Group ID Service

URL

The Group ID Service url is:

http://tolweb.org/onlinecontributors/app?service=external&page=xml/GroupSearchService&group=xxx

where xxx is the name of the group for which you want to retrieve the unique ToL identifier.

Parameters

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:

http://tolweb.org/onlinecontributors/app?service=external&page=xml/GroupSearchService&group=Bembidion

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).

Response Format

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.

Example:

<?xml version="1.0" standalone="yes"?>
<NODES COUNT="1">
<NODE ID="194">
<NAME><![CDATA[Bembidion]]></NAME>
</NODE>
</NODES>

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

URL

The tree structure service url is

http://tolweb.org/onlinecontributors/app?service=external&page=xml/TreeStructureService&node_id=yyy

where yyy is the unique identifier for a group in the ToL database.

Parameters

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:

http://tolweb.org/Bembidion/194

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

EXTINCT	0 - node is not extinct 2 - node is extinct
ID	The unique identifier for the node on the Tree of Life Web Project
CONFIDENCE	Confidence of placement in the tree structure: 0 - confident 1 - incertae sedis in putative position 2 - incertae sedis position unspecified (no putative position in parent group)
PHYLESIS	0 - monophyletic 1 - monophyly uncertain 2 - not monophyletic
LEAF	1 - the node represents a leaf in the Tree of Life (may be applied to species, subspecies, populations, strains) 0 - the node does not represent a leaf (it has or will have descendent nodes on the Tree of Life)
HASPAGE	1 - the node has a page on the Tree of Life Web Project 0 - it doesn't
ITALICIZENAME	1 - the node name should be printed in italics 0 - it should not be printed in italics
INCOMPLETESUBGROUPS	1 - the immediate descendents of the current node do not represent all known subgroups 0 - all immediate subgroups are represented (although they may not all be fleshed out to the leaves of the tree)
SHOWAUTHORITY	1 - show authority data on the ToL web page for this group 0 - don't show authority data
SHOWAUTHORITYCONTAINING	1 - show authority data on the tree/list of the ToL web page for the containing group 0 - don't show authority data
IS_NEW_COMBINATION	1 - the node name is a new combination 0 - it's not a new combination
COMBINATION_DATE	Publication date of the new combination
CHILDCOUNT	Number of descendent nodes.

OTHERNAME Attributes Summary

ISIMPORTANT	1 - important other name: use as subtitle on ToL web pages 0 - not an important other name
ISPREFERRED	1 - preferred other name: use as supertitle on ToL web pages 0 - not a preferred other name
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.
ITALICIZENAME	1 - the other name should be printed in italics 0 - it should not be printed in italics

Disclaimer

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.

Terms of Use

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.

Future Plans

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.