POST /api/v1/taxa2tree
Returns the taxonomic tree for a given list of taxon identifiers.
This method constructs and returns the taxonomic tree for a given list of NCBI taxon identifiers.
Request
The taxa2tree method can be used by doing a HTTP POST-request (preferred) or GET-request to http://api.unipept.ugent.be/api/v1/taxa2tree. Parameters can be included in the request body (POST) or in the query string (GET). The only required parameter is input[], which takes at least one taxon identifier.
input
input[] is a required parameter that takes at least one taxon identifier. Unipept will compute and return the taxonomic tree for the given taxa. To pass multiple taxon identifiers, simply add multiple input[] parameters (see example).
Response
The taxonomic tree for the given list of taxon identifiers is returned as a JSON object. This object is a tree that's represented by a hierarchical construction of nodes. By default, the object contains the following information fields extracted from the NCBI taxonomy:
id: the NCBI taxon id of the node.name: the name of the node.rank: the taxonomic rank of the node.data: extra information associated with this node.count: how many of the given taxa are directly or indirectly associated with this node? (e.g. correspond to the node itself or one of it's children)self_count: how many of the given taxa are directly associated with this node?children: a list of nodes that are the children of this node in the NCBI-taxonomy. These have the same structure as the root JSON-object.
GET-parameters
| Name | Description |
|---|---|
|
input[] required |
List of taxon identifiers to calculate the taxonomic tree for. Add multiple parameters to specify multiple taxon id's. Value: Integer |
|
link optional |
Return an URL that points to a GitHub gist in which the visualization code for this sample is stored. Value: boolean |
POST-parameters
| Name | Description |
|---|---|
|
count required |
List of taxon identifiers and associated counts to calculate the taxonomic tree for. Should be a JSON-object with taxon id's as keys and counts as values. Value: object |
|
link optional |
Return an URL that points to a GitHub gist in which the visualization code for this sample is stored. Value: boolean |
Examples
Example Calculate the taxonomic tree for a given list of taxon identifiers
This example calculates and retrieves the taxonomic tree of Bacteroides fragilis (taxon id 817), Bacteroides intestinalis (taxon id 329854) and Coprobacter fastidiosus (taxon id 1099853).
POST$ curl -X POST -H 'Accept: application/json' api.unipept.ugent.be/api/v1/taxa2lca \ -d 'input[]=817' \ -d 'input[]=329854' \ -d 'input[]=1099853'GET
http://api.unipept.ugent.be/api/v1/taxa2lca.json?input[]=817&input[]=329854&input[]=1099853
Response
{
"id": 1,
"name": "Organism",
"rank": "root",
"data": {
"count": 3,
"self_count": 0
},
"children": [
{
"id": 2,
"name": "Bacteria",
"rank": "superkingdom",
"data": {
"count": 3,
"self_count": 0
},
"children": [
{
"id": 976,
"name": "Bacteroidetes",
"rank": "phylum",
"data": {
"count": 3,
"self_count": 0
},
"children": [
{
"id": 200643,
"name": "Bacteroidia",
"rank": "class_",
"data": {
"count": 3,
"self_count": 0
},
"children": [
{
"id": 171549,
"name": "Bacteroidales",
"rank": "order",
"data": {
"count": 3,
"self_count": 0
},
"children": [
{
"id": 815,
"name": "Bacteroidaceae",
"rank": "family",
"data": {
"count": 2,
"self_count": 0
},
"children": [
{
"id": 816,
"name": "Bacteroides",
"rank": "genus",
"data": {
"count": 2,
"self_count": 0
},
"children": [
{
"id": 817,
"name": "Bacteroides fragilis",
"rank": "species",
"data": {
"count": 1,
"self_count": 1
},
"children": []
},
{
"id": 329854,
"name": "Bacteroides intestinalis",
"rank": "species",
"data": {
"count": 1,
"self_count": 1
},
"children": []
}
]
}
]
},
{
"id": 2005519,
"name": "Barnesiellaceae",
"rank": "family",
"data": {
"count": 1,
"self_count": 0
},
"children": [
{
"id": 1348911,
"name": "Coprobacter",
"rank": "genus",
"data": {
"count": 1,
"self_count": 0
},
"children": [
{
"id": 1099853,
"name": "Coprobacter fastidiosus",
"rank": "species",
"data": {
"count": 1,
"self_count": 1
},
"children": []
}
]
}
]
}
]
}
]
}
]
}
]
}
]
}Example Retrieve the taxonomic tree and its lineage for a given list of taxon identifiers
This example calculates and retrieves the taxonomic lowest common ancestor of Bacteroides fragilis (taxon id 817), Bacteroides intestinalis (taxon id 329854) and Coprobacter fastidiosus (taxon id 1099853), including its complete lineage.
POST$ curl -X POST -H 'Accept: application/json' api.unipept.ugent.be/api/v1/taxa2tree \ --data '{"counts": {"817": 3, "329854": 5, "1099853": 7}}'GET
Can only be performed with a POST-request
Response
{
"id": 1,
"name": "Organism",
"rank": "root",
"data": {
"count": 15,
"self_count": 0
},
"children": [
{
"id": 2,
"name": "Bacteria",
"rank": "superkingdom",
"data": {
"count": 15,
"self_count": 0
},
"children": [
{
"id": 976,
"name": "Bacteroidetes",
"rank": "phylum",
"data": {
"count": 15,
"self_count": 0
},
"children": [
{
"id": 200643,
"name": "Bacteroidia",
"rank": "class_",
"data": {
"count": 15,
"self_count": 0
},
"children": [
{
"id": 171549,
"name": "Bacteroidales",
"rank": "order",
"data": {
"count": 15,
"self_count": 0
},
"children": [
{
"id": 815,
"name": "Bacteroidaceae",
"rank": "family",
"data": {
"count": 8,
"self_count": 0
},
"children": [
{
"id": 816,
"name": "Bacteroides",
"rank": "genus",
"data": {
"count": 8,
"self_count": 0
},
"children": [
{
"id": 817,
"name": "Bacteroides fragilis",
"rank": "species",
"data": {
"count": 3,
"self_count": 3
},
"children": []
},
{
"id": 329854,
"name": "Bacteroides intestinalis",
"rank": "species",
"data": {
"count": 5,
"self_count": 5
},
"children": []
}
]
}
]
},
{
"id": 2005519,
"name": "Barnesiellaceae",
"rank": "family",
"data": {
"count": 7,
"self_count": 0
},
"children": [
{
"id": 1348911,
"name": "Coprobacter",
"rank": "genus",
"data": {
"count": 7,
"self_count": 0
},
"children": [
{
"id": 1099853,
"name": "Coprobacter fastidiosus",
"rank": "species",
"data": {
"count": 7,
"self_count": 7
},
"children": []
}
]
}
]
}
]
}
]
}
]
}
]
}
]
}Example Retrieve the taxonomic lowest common ancestor and its lineage and names for a given list of taxon identifiers
This example retrieves the taxonomic tree of Bacteroides fragilis (taxon id 817), Bacteroides intestinalis (taxon id 329854) and Coprobacter fastidiosus (taxon id 1099853), including its complete lineage with names.
POST$ curl -X POST -H 'Accept: application/json' api.unipept.ugent.be/api/v1/taxa2lca \ -d 'input[]=817' \ -d 'input[]=329854' \ -d 'input[]=1099853' \ -d 'link=true'GET
http://api.unipept.ugent.be/api/v1/taxa2tree.json?input[]=817&input[]=329854&input[]=1099853&link=true
Response
{"gist":"https://gist.github.com/1d3e41bf41c4ca5b97aa802c58484393"}Try it
Use the API explorer form below to call the taxa2tree method on live data and see the response.
Request
Response