Unipept

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 ancestor
  • taxon_name: the name of the taxonomic lowest common ancestor
  • taxon_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.

Value: Must be true or false (default)
names
optional

Return names of ranks in the lineage if true.

Value: Must be 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

Back to top