Studies API v3

Source trees are associated with studies (publications), and one study can contain multiple trees. OpenTree uses a Git repository of NexSON files as the central document store, 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.

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
/studies/find_studies	POST	Return a list of studies that match a given property. If no property provided, returns a list of all studies.
/studies/find_trees	POST	Return a list of trees (and the studies that contain them) that match a given property.
/studies/properties	POST	Return a list of properties that can be used to search studies and trees.
/study/{STUDY_ID}	GET	Return a study.
/study/{STUDY_ID}/tree/{TREE_ID}	GET	Return a tree from within a study.

find_studies

Return a list of studies that match a given property.

POST    /studies/find_studies

Perform a simple search for indexed studies. To find all studies, omit both the property and the value from your query.

Input parameters

Parameters with bold type definitions are required.

• exact : (boolean) Whether to perform exact matching ONLY. Defaults to false, i.e. fuzzy matching is enabled. Note that fuzzy matching is only available for some string properties.
• property : (string) The property to be searched. A list of searchable properties is available from the properties service (note that the 'find_studies' and 'find_trees' services have distinct search properties). To find all studies, omit both the property and the value from your query.
• value : (string) The value to be searched. This must be passed as a string, but will be converted to the datatype corresponding to the specified searchable value. To find all studies, omit both the property and the value from your query.
• verbose : (boolean) Whether or not to include all metadata. By default, verbose=false and returns only the studyId

Output parameter

• matched_studies: (list) List of study descriptors, each with fields as follows:

• ot:studyPublicationReference : (string) The full publication reference for the study. Only returned if verbose=true.

• ot:curatorName : (string) The name of the most recent curator. Only returned if verbose=true.

• ot:studyId : (string) The study ID

• ot:studyYear : (integer) The publication year of the study. Only returned if verbose=true.

• ot:focalClade : (integer) The OTT Id of the focal clade. Only returned if verbose=true.

• ot:focalCladeOTTTaxonName : (string) The taxon name of the focal clade. Only returned if verbose=true.

• ot:dataDeposit : (string) The URL where data is permananently archived for this study (e.g. in TreeBASE, or Dryad, or some other data archive). Only returned if verbose=true.

• ot:studyPublication : (string) The URL for the study (usually a DOI). Only returned if verbose=true.

Example command:

$ curl -X POST https://api.opentreeoflife.org/v3/studies/find_studies \
-H "content-type:application/json" -d \
'{"property":"ot:studyId","value":"pg_719","verbose":true}'

Example result:

{
  "matched_studies" : [ {
    "ot:studyPublicationReference" : "Tippery N., & Les D. 2011. Phylogenetic relationships and morphological evolution in Nymphoides (Menyanthaceae). Systematic Botany, 36: 1101-1113.",
    "ot:curatorName" : "bryan drew",
    "ot:studyId" : "pg_719",
    "ot:studyYear" : 2011,
    "ot:focalClade" : 694622,
    "ot:focalCladeOTTTaxonName" : "Menyanthaceae",
    "ot:dataDeposit" : "http://purl.org/phylo/treebase/phylows/study/TB2:S11079",
    "ot:studyPublication" : "http://dx.doi.org/10.1600/036364411X605092"
  } ]
}

find_trees

Return a list of trees (and the studies that contain them) that match a given property.

POST    /studies/find_trees

Perform a simple search for trees in indexed studies.

Input parameters

Parameters with bold type definitions are required.

• property : (string) The property to be searched on. A list of searchable properties is available from the properties service (note that the 'find_studies' and 'find_trees' services have distinct search properties).
• value : (string) The value to be searched. This must be passed as a string, but will be converted to the datatype corresponding to the specified searchable value.
• exact : (boolean) Whether to perform exact matching ONLY. Defaults to false, i.e. fuzzy matching is enabled. Fuzzy matching is only available for some string properties.
• verbose : (boolean) Whether or not to include all metadata. By default, returns only minimal information to identify the study and tree

Output parameter

• matched_studies: (list) List of study descriptors, each with fields as follows:

• ot:studyPublicationReference : (string) The full publication reference for the study. Only returned if verbose=true.

• ot:curatorName : (string) The name of the most recent curator. Only returned if verbose=true.

• ot:studyId : (string) The study ID

• ot:studyYear : (integer) The publication year of the study. Only returned if verbose=true.

• ot:focalClade : (integer) The OTT Id of the focal clade. Only returned if verbose=true.

• ot:focalCladeOTTTaxonName : (string) The taxon name of the focal clade. Only returned if verbose=true.

• ot:dataDeposit : (string) The URL where data is permananently archived for this study (e.g. in TreeBASE, or Dryad, or some other data archive). Only returned if verbose=true.

• ot:studyPublication : (string) The URL for the study (usually a DOI). Only returned if verbose=true.

• matched_trees : (list of dict) A list of all matching trees in this study. Each match includes the following tree metadata: ot:studyId, ot:ottId, ot:branchLengthMode, ot:originalLabel, oti_tree_id, ot:ottTaxonName, and ot:branchLengthDescription

Example command:

$ curl -X POST https://api.opentreeoflife.org/v3/studies/find_trees \
-H "content-type:application/json" -d \
'{"property":"ot:ottTaxonName","value":"Solifugae","verbose":true}'

Example result:

{
  "matched_studies" : [ {
    "ot:studyPublicationReference" : "Klompen H., Lekveishvili M., & Iv W. 2006. Phylogeny of parasitiform mites (Acari) based on rRNA. Molecular Phylogenetics and Evolution, null.",
    "ot:curatorName" : "Chris Owen",
    "ot:studyId" : "pg_1793",
    "matched_trees" : [ {
      "ot:studyId" : "pg_1793",
      "ot:branchLengthMode" : "ot:posteriorSupport",
      "oti_tree_id" : "pg_1793_tree3630",
      "ot:branchLengthDescription" : ""
    } ],
    "ot:studyYear" : 2006,
    "ot:focalClade" : 150786,
    "ot:focalCladeOTTTaxonName" : "Parasitiformes",
    "ot:dataDeposit" : "http://purl.org/phylo/treebase/phylows/study/TB2:S1707",
    "ot:studyPublication" : "http://dx.doi.org/10.1016/j.ympev.2006.10.024"
  } ]
}

properties

Return a list of properties that can be used to search studies and trees.

POST    /studies/properties

Get a list of properties that can be used to search for studies and trees.

Input parameters

None

Output parameters

• tree_properties : (list of string) The list of searchable tree properties
• study_properties : (list of string) The list of searchable study properties

Example command:

$ curl -X POST https://api.opentreeoflife.org/v3/studies/properties

Example result:

{
  "tree_properties" : [ "ot:treebaseOTUId", "ot:nodeLabelMode", "ot:originalLabel", "oti_tree_id", "ot:ottTaxonName", "ot:inferenceMethod", "ot:tag", "ot:treebaseTreeId", "ot:comment", "ot:branchLengthDescription", "ot:treeModified", "ot:studyId", "ot:branchLengthTimeUnit", "ot:ottId", "ot:branchLengthMode", "ot:treeLastEdited", "ot:nodeLabelDescription" ],
  "study_properties" : [ "ot:studyModified", "ot:focalClade", "ot:focalCladeOTTTaxonName", "ot:focalCladeOTTId", "ot:studyPublication", "ot:studyLastEditor", "ot:focalCladeTaxonName", "ot:tag", "ot:comment", "ot:studyLabel", "ot:authorContributed", "ot:studyPublicationReference", "ot:curatorName", "ot:studyId", "ot:studyUploaded", "ot:studyYear", "ot:dataDeposit" ]
}

study

Return a study.

GET    /study/{STUDY_ID}

Given a studyID, return a JSON object. The 'data' property of that object will hold the NexSON of that study. If the URL ends with a file extension, then the file type will be inferred for file conversion:

.nex -> NEXUS
.tre -> Newick
.nexml -> NeXML
.nexson, .json, or no extension -> NexSON

For NEXUS and Newick formats, by default tip labels will be those from the originally uploaded study. Alternate labels can be accessed using tip_label argument. Values must be one of ot:originallabel, ot:ottid, or ot:otttaxonname.

More detailed documentation of the possible arguments and return values (including as NeXML, NEXUS, or newick) are at phylesystem-api/docs/README.md

Example commands:

The first returns JSON, the others return NEXUS with two different label formats.

$ curl https://api.opentreeoflife.org/v3/study/pg_1144
$ curl https://api.opentreeoflife.org/v3/study/pg_1144.nex/?tip_label=ot:ottid
$ curl https://api.opentreeoflife.org/v3/study/pg_1144.nex/?tip_label=ot:otttaxonname

Due to size of response, we don't show sample results here

tree

Return a tree from within a study.

GET    /study/{STUDY_ID}/tree/{TREE_ID}

Given a studyID and the ID of one of its trees, return a JSON object for the tree. As for the study method, more detailed documentation of the possible arguments and return values (including as NEXUS or newick) are at phylesystem-api/docs/README.md

NexSON supports fine-grained access to parts of the study (see below). NeXML can only be returned for the study. Newick and NEXUS formats can only return the full study, trees or subtrees.

Example command:

$ curl https://api.opentreeoflife.org/v3/study/pg_1144/tree/tree2324

Due to size of response, we don't show sample results here