POST /api/v1/taxa2lca
Returns the taxonomic lowest common ancestor for a given list of taxon identifiers.
This method calculates and returns the taxonomic lowest common ancestor for a given list of NCBI taxon identifiers.
Request
The pept2taxa method can be used by doing a HTTP POST-request (preferred) or GET-request to http://api.unipept.ugent.be/api/v1/pept2lca
. 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 two taxon identifiers.
input
input[]
is a required parameter that takes at least two taxon identifiers. Unipept will calculate and return the taxonomic lowest common ancestor of the given taxa. To pass multiple taxon identifiers, simply add multiple input[]
parameters (see example).
extra
extra
is an optional parameter and can either be true
or false
. When not set explicitly, the parameter defaults to false
. When the parameter is set to true
, Unipept will return the complete lineage of the taxonomic lowest common ancestor. See the response section for an overview of the information fields returned.
names
names
is an optional parameter and can either be true
or false
. When not set explicitly, the parameter defaults to false
. When both names
and extra
are set to true
, Unipept will return the names of all ranks in the lineage of the taxonomic lowest common ancestor. Setting only names
to true
will not result in additional information fields being returned. See the response section for an overview of the information fields returned.
Performance penalty
Setting names
to true
has a performance penalty inferred from additional database queries. Do not use this parameter unless the extra information fields are needed.
Response
The taxonomic lowest common ancestor for the given list of taxon identifiers is returned as a JSON object. By default, the object contains the following information fields extracted from the NCBI taxonomy:
taxon_id
: the NCBI taxon id of the taxonomic lowest common ancestortaxon_name
: the name of the taxonomic lowest common ancestortaxon_rank
: the taxonomic rank of the taxonomic lowest common ancestor
When the extra
parameter is set to true
, the object contains additional information about the lineage of the taxonomic lowest common ancestor extracted from the NCBI taxonomy. The taxon id of each rank in the lineage is specified using the following information fields:
superkingdom_id
kingdom_id
subkingdom_id
superphylum_id
phylum_id
subphylum_id
superclass_id
class_id
subclass_id
infraclass_id
superorder_id
order_id
suborder_id
infraorder_id
parvorder_id
superfamily_id
family_id
subfamily_id
tribe_id
subtribe_id
genus_id
subgenus_id
species_group_id
species_subgroup_id
species_id
subspecies_id
varietas_id
forma_id
When both the names
and extra
parameters are set to true
, objects also contain the names for each rank in the lineage using the following information fields:
superkingdom_name
kingdom_name
subkingdom_name
superphylum_name
phylum_name
subphylum_name
superclass_name
class_name
subclass_name
infraclass_name
superorder_name
order_name
suborder_name
infraorder_name
parvorder_name
superfamily_name
family_name
subfamily_name
tribe_name
subtribe_name
genus_name
subgenus_name
species_group_name
species_subgroup_name
species_name
subspecies_name
varietas_name
forma_name
Parameters
Name | Description |
---|---|
input[] required |
List of taxon identifiers to calculate the lowest common ancestor for. Add multiple parameters to specify multiple taxon id's. Value: Integer |
extra optional |
Return additional lineage information fields if true or false (default)
|
names optional |
Return names of ranks in the lineage if true or false (default)
|
Examples
Example Calculate the taxonomic lowest common ancestor 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).
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
{
taxon_id: 171549,
taxon_name: 'Bacteroidales',
taxon_rank: 'order'
}
Example Retrieve the taxonomic lowest common ancestor 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/taxa2lca \ -d 'input[]=817' \ -d 'input[]=329854' \ -d 'input[]=1099853' \ -d 'extra=true'GET
http://api.unipept.ugent.be/api/v1/taxa2lca.json?input[]=817&input[]=329854&input[]=1099853&extra=true
Response
{
taxon_id: 171549,
taxon_name: 'Bacteroidales',
taxon_rank: 'order',
superkingdom_id: 2,
kingdom_id: null,
subkingdom_id: null,
superphylum_id: 68336,
phylum_id: 976,
subphylum_id: null,
superclass_id: null,
class_id: 200643,
subclass_id: null,
infraclass_id: null,
superorder_id: null,
order_id: 171549,
suborder_id: null,
infraorder_id: null,
parvorder_id: null,
superfamily_id: null,
family_id: null,
subfamily_id: null,
tribe_id: null,
subtribe_id: null,
genus_id: null,
subgenus_id: null,
species_group_id: null,
species_subgroup_id: null,
species_id: null,
subspecies_id: null,
varietas_id: null,
forma_id: null
}
Example Retrieve the taxonomic lowest common ancestor and its lineage and names for a given list of taxon identifiers
This example 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 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 'extra=true' \ -d 'names=true'GET
http://api.unipept.ugent.be/api/v1/taxa2lca.json?input[]=817&input[]=329854&input[]=1099853&extra=true&names=true
Response
{
taxon_id: 171549,
taxon_name: 'Bacteroidales',
taxon_rank: 'order',
superkingdom_id: 2,
superkingdom_name: 'Bacteria',
kingdom_id: null,
kingdom_name: '',
subkingdom_id: null,
subkingdom_name: '',
superphylum_id: 68336,
superphylum_name: 'Bacteroidetes/Chlorobi group',
phylum_id: 976,
phylum_name: 'Bacteroidetes',
subphylum_id: null,
subphylum_name: '',
superclass_id: null,
superclass_name: '',
class_id: 200643,
class_name: 'Bacteroidia',
subclass_id: null,
subclass_name: '',
infraclass_id: null,
infraclass_name: '',
superorder_id: null,
superorder_name: '',
order_id: 171549,
order_name: 'Bacteroidales',
suborder_id: null,
suborder_name: '',
infraorder_id: null,
infraorder_name: '',
parvorder_id: null,
parvorder_name: '',
superfamily_id: null,
superfamily_name: '',
family_id: null,
family_name: '',
subfamily_id: null,
subfamily_name: '',
tribe_id: null,
tribe_name: '',
subtribe_id: null,
subtribe_name: '',
genus_id: null,
genus_name: '',
subgenus_id: null,
subgenus_name: '',
species_group_id: null,
species_group_name: '',
species_subgroup_id: null,
species_subgroup_name: '',
species_id: null,
species_name: '',
subspecies_id: null,
subspecies_name: '',
varietas_id: null,
varietas_name: '',
forma_id: null,
forma_name: ''
}
Try it
Use the API explorer form below to call the taxa2lca method on live data and see the response.
Request
Response