Skip to content

Open Tree of Life APIs V1

Jump to bottom Edit New page
kcranston edited this page Sep 9, 2014 · 1 revision

This documentation applies to Version 1.0 of the Open Tree of Life APIs. While we have no plans to deprecate these methods, this is likely at some point in the future. Please see the documentation for the current version of the API if you are developing new tools that use the APIs.

The Open Tree of Life APIs include services to access the following types of data:

  • synthetic tree: the single binary draft tree of life that is a combination of the source trees and the opentree reference taxonomy
  • taxonomy: the opentree taxonomy (OTT), as well as lists of synonyms and homonyms
  • source trees: organized into studies, where a single study can include multiple trees

The base URL for all services:

http://api.opentreeoflife.org/

Caveats

  • this doc includes the base list of methods to generate projects for a September 2014 hackathon. We hope that that event will generate ideas (and code!) for additions and improvement
  • the Open Tree APIs are in heavy development. Future version will certainly add new methods, change method parameters, and change return values, but we aim to maintain documented behaviour of v1 methods.
  • the JSON return values are not consistent between software components. We are working to standardize on the documented NexSON format.
  • neo4j implements POST for some methods that really should be GET.

Questions / Comments

If you have questions, or have a problem with any of these methods, please leave an issue in the feedback issue tracker.

Synthetic tree methods

These methods require OTT (Open Tree Taxonomy) IDs, not names. See taxonomy methods for methods to get OTT IDs from names. Detailed descriptions below the summary table.

| URL | Verb | Summary |
|--------------------------------|--------|----------------------|--------| | /getSyntheticTree | POST | Returns subtree of synthetic tree starting from specified node | | /getDraftTreeSubtreeForNodes | POST | Get pruned subtree descended for list of taxa |
| /getSynthesisSourceList | POST | Get list of inputs to the synthetic tree |

Get complete subtree below node

POST    /treemachine/v1/getSyntheticTree

Returns a subtree from the specified synthetic tree, in the desired format ('newick' or 'arguson'). If format is "newick" then return JSON will have two fields: "newick" and "treeID". If format = "arguson" then the return object will be the form of JSON expected by the argus tree viewer.

N.B. The next version of this method will implement a limit on the total number of nodes in the subtree.

Parameter treeID = id of the parent synthetic tree (string); defaults to current synthetic tree

Parameter format = desired format, either "arguson" or "newick" (string); defaults to arguson

Parameter maxDepth = desired depth of subtree, i.e. max number of edges between the leaves and root node. A negative number means no limit will be applied. The default value is 5. (integer)

Parameter subtreeNodeID = starting/root node for returned subtree (string); defaults to root of synthetic tree ('cellular organisms')

Example:

$ curl -X POST http://api.opentreeoflife.org/treemachine/v1/getSyntheticTree -H "content-type:application/json" -d '{"treeID":"otol.draft.22", "format":"arguson", "maxDepth":"3", "subtreeNodeID":"3534540"}'

Get pruned subtree for taxon list

POST    /treemachine/v1/getDraftTreeSubtreeForNodes

Returns a JSON object with two properties:

  • found_nodes is a list of node identifiers found, and
  • subtree will hold a Newick representation of the synthetic tree with tips corresponding to the set of nodes identified by the query input. Branch lengths may be arbitrary, and the leaf labels of the tree will be taxonomic names

Accepts either OTT ids (external use) or treemachine node ids (internal use) as input.

Parameter nodeIds = array of node ids

Parameter ottIds = array of OTT ids

Example:

$ curl -X POST http://api.opentreeoflife.org/treemachine/v1/getDraftTreeSubtreeForNodes -H "content-type:application/json" -d '{"ottIds":[515698,515712,149491,876340,505091,840022,692350,451182,301424,876348,515698,1045579,267484,128308,380453,678579,883864,863991,3898562,23821,673540,122251,106729,1084532,541659]}'

Get list of inputs to synthetic tree

POST    /treemachine/v1/getSynthesisSourceList

Returns all inputs that contributed to the synthetic tree as array of [studyID_treeID]:

[ "244_3855", "2879_6674", "2878_6673", "412_2166", "2827_6577", ..., "2849_6615", "taxonomy" ]

In v1 of the API, this will have the tree specifiers parsed out as { “study”: “244”, “tree”:”3855” } or something similar to that.

Example:

$ curl -X POST http://api.opentreeoflife.org/treemachine/v1/getSynthesisSourceList

Taxonomy methods

URL Verb Summary
/taxomachine/v1/contextQueryForNames POST Return matches for taxon names using taxonomic contexts using contexts to disambiguate names
/taxomachine/v1/getContextForNames POST Infer the taxonomic context for a set of taxon names
/taxomachine/v1/getContextsJSON POST Return the list of available taxonomic contexts
/taxomachine/v1/autocompleteBoxQuery POST Return possible matches for a taxon name prefix

Return matches for taxon names using taxonomic contexts (to disambiguate names)

POST    /taxomachine/v1/contextQueryForNames

Accepts one or more taxonomic names and returns information about potential matches for these names to known taxa in OTT. This service uses taxonomic contexts to disambiguate homonyms and misspelled names. Taxonomic contexts are taxonomically uncontested clades that have been designated for use as contexts. A context may be specified using the contextName parameter, or if not specified then it will be inferred as the shallowest taxonomic context that contains all the unambiguous names in the input set. A name is considered unambiguous if it is not a synonym and has only one exact match to any taxon name in OTT. Once a context has been identified (either specified or by inference), all taxon name matches will performed only against taxa within that context.

For a list of available taxonomic contexts, see the getContexts service.

Example:

curl -X POST http://api.opentreeoflife.org/taxomachine/v1/contextQueryForNames -H "content-type:application/json" -d '{"names":["Aster","Symphyotrichum","Erigeron","Campanula","Barnadesia"]}'

Returns JSON containing search parameters and possible matches to names.

{
  "context" : "Asterids",
  "unmatched_name_ids" : [ ],
  "governing_code" : "ICBN",
  "matched_name_ids" : [ "Barnadesia", "Campanula", "Erigeron", "Aster", "Symphyotrichum" ],
  "unambiguous_name_ids" : [ "Barnadesia", "Campanula", "Erigeron", "Aster", "Symphyotrichum" ],
  "results" : [ {
    "id" : "Barnadesia",
    "matches" : [ {
      "dubious_name" : false,
      "is_synonym" : false,
      "flags" : [ ],
      "is_perfect_match" : true,
      "search_string" : "barnadesia",
      "score" : 1.0,
      "is_approximate_match" : false,
      "is_homonym" : false,
      "matched_ott_id" : 515698,
      "matched_node_id" : 3216888,
      "rank" : "",
      "matched_name" : "Barnadesia",
      "unique_name" : "Barnadesia",
      "nomenclature_code" : "ICBN",
      "synonym_or_homonym_status" : "known",
      "parent_name" : "Barnadesioideae",
      "source_name" : "ott"
    } ]
  }, {
    "id" : "Campanula",
    "matches" : [ {
      "dubious_name" : false,
      "is_synonym" : false,
      "flags" : [ ],
      "is_perfect_match" : true,
      "search_string" : "campanula",
      "score" : 1.0,
      "is_approximate_match" : false,
      "is_homonym" : false,
      "matched_ott_id" : 590452,
      "matched_node_id" : 3241097,
      "rank" : "",
      "matched_name" : "Campanula",
      "unique_name" : "Campanula",
      "nomenclature_code" : "ICBN",
      "synonym_or_homonym_status" : "known",
      "parent_name" : "Campanulaceae",
      "source_name" : "ott"
    } ]
  }, {
    "id" : "Aster",
    "matches" : [ {
      "dubious_name" : false,
      "is_synonym" : false,
      "flags" : [ ],
      "is_perfect_match" : true,
      "search_string" : "aster",
      "score" : 1.0,
      "is_approximate_match" : false,
      "is_homonym" : false,
      "matched_ott_id" : 409712,
      "matched_node_id" : 3231137,
      "rank" : "",
      "matched_name" : "Aster",
      "unique_name" : "Aster",
      "nomenclature_code" : "ICBN",
      "synonym_or_homonym_status" : "known",
      "parent_name" : "Australasian lineages",
      "source_name" : "ott"
    } ]
  }, {
    "id" : "Erigeron",
    "matches" : [ {
      "dubious_name" : false,
      "is_synonym" : false,
      "flags" : [ ],
      "is_perfect_match" : true,
      "search_string" : "erigeron",
      "score" : 1.0,
      "is_approximate_match" : false,
      "is_homonym" : false,
      "matched_ott_id" : 643717,
      "matched_node_id" : 3233546,
      "rank" : "",
      "matched_name" : "Erigeron",
      "unique_name" : "Erigeron",
      "nomenclature_code" : "ICBN",
      "synonym_or_homonym_status" : "known",
      "parent_name" : "North American clade",
      "source_name" : "ott"
    } ]
  }, {
    "id" : "Symphyotrichum",
    "matches" : [ {
      "dubious_name" : false,
      "is_synonym" : false,
      "flags" : [ ],
      "is_perfect_match" : true,
      "search_string" : "symphyotrichum",
      "score" : 1.0,
      "is_approximate_match" : false,
      "is_homonym" : false,
      "matched_ott_id" : 1058735,
      "matched_node_id" : 3234798,
      "rank" : "",
      "matched_name" : "Symphyotrichum",
      "unique_name" : "Symphyotrichum",
      "nomenclature_code" : "ICBN",
      "synonym_or_homonym_status" : "known",
      "parent_name" : "North American clade",
      "source_name" : "ott"
    } ]
  } ]
}

Infer the taxonomic context for a set of taxon names

POST    /taxomachine/v1/getContextForNames

Find the least inclusive taxonomic context that includes all the unambiguous names in the input set. Ambiguous names (i.e. names with exact matches to non-homonym taxa) are indicated in results.

Example:

curl -X POST http://api.opentreeoflife.org/taxomachine/v1/getContextForNames -H "content-type:application/json" -d '{"names":["Pan","Homo","Bos","Mus","Bufo"]}'

{
  "context_name" : "Tetrapods",
  "content_rootnode_ott_id" : 229562,
  "ambiguous_names" : [ ]
}

Return the list of available taxonomic contexts

POST    /taxomachine/v1/getContextsJSON

Returns a list containing all available taxonomic context names (i.e. all the valid input values for the contextName fields of other services), organized by group.

Example:

curl -X POST http://api.opentreeoflife.org/taxomachine/v1/getContextsJSON

Returns JSON containing the list of available taxonomic contexts

{
  "FUNGI" : [ "Fungi" ],
  "BACTERIA" : [ "Bacteria" ],
  "LIFE" : [ "All life" ],
  "ANIMALS" : [ "Animals", "Birds", "Tetrapods", "Mammals", "Amphibians", "Vertebrates", "Arthropods", "Molluscs", "Platyhelminthes", "Annelids", "Cnidarians", "Arachnides", "Insects" ],
  "PLANTS" : [ "Land plants", "Hornworts", "Mosses", "Liverworts", "Vascular plants", "Club mosses", "Ferns", "Seed plants", "Flowering plants", "Monocots", "Eudicots", "Asterids", "Rosids" ]
}

Get matches to taxon name prefix

POST    /taxomachine/v1/autocompleteBoxQuery

Assumes the input is a taxon name that may be incomplete (i.e. the beginning of a taxon name such as "Aste", which would match "Aster", "Asteroidea", "Asteraceae", "Aster laevis", etc.). This service is optimized and (obviously) intended for use with autocomplete boxes on web forms. It should not be used for general purpose TNRS queries against OTT (use contextQueryForNames instead).

Example:

$ curl -X POST http://api.opentreeoflife.org/taxomachine/v1/autocompleteBoxQuery -H "content-type:application/json" -d '{"queryString":"Endoxyla","contextName":"All life"}'

Returns JSON of taxon name matches:

[
	{ 
		"ottId" : 1098009, 
		"nodeId" : 1590418, 
		"exact" : false, 
		"name" : "Endoxyla (genus in family Cossidae)", 
		"higher" : true 
	}, 
	{ 
		"ottId" : 4054899, 
		"nodeId" : 149672, 
		"exact" : false, 
		"name" : "Endoxyla (if:1813,ncbi:1289957,gbif:2572474)", 
		"higher" : true 
	}, 
	{ 
		"ottId" : 429888, 
		"nodeId" : 149744, 
		"exact" : false, 
		"name" : "Endoxyla (ncbi:255778)", 
		"higher" : true 
	}
]

Source tree methods

OpenTree uses a Git repository of NexSON files as the central datastore, called phylesystem. Code for an API for the OpenTree treestore is in this Github repository and there is detailed documentation of the datastore API. We also have a study index in neo4j that provides methods that search across studies.

URL Verb Summary
/phylesystem/v1/study GET Return a single study ID
/phylesystem/v1/study_list GET Returns list of all studies

Return list of all studies

GET /phylesystem/v1/study_list

Returns array of study IDs.

Example:

$ curl -L http://api.opentreeoflife.org/phylesystem/v1/study_list

Return a single study

GET     /phylesystem/v1/study

Given a studyID, return a JSON object. The "data" property of that object will hold the NexSON of that study. More detailed documentation of the possible arguments and return values are at phylesystem-api/docs/README.md

Example:

$ curl -L http://api.opentreeoflife.org/phylesystem/v1/study/pg_719

Other API docs

The following links provide information about ongoing development: methods being tested, developed or discussed.

If you have questions or feedback, leave an issue on GitHub or join us on IRC on the #opentreeoflife channel on Freenode.

Add a custom footer
Add a custom sidebar
Clone this wiki locally