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": []
                                                        }
                                                    ]
                                                }
                                            ]
                                        }
                                    ]
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    ]
}

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