Categoria: Services

NCBI Local Taxonomy API — User Manual

Documentation for the high-performance taxonomic lineage resolution service.

Welcome to the Local Taxonomy API documentation hosted by the Center for Molecular Biology and Genetic Engineering (CBMEG) at Unicamp.

This high-performance API allows you to retrieve the full, lineage-resolved taxonomic classification for any NCBI Taxonomic Identifier (TaxID). The service runs entirely on local infrastructure, bypassing external network latencies and NCBI rate limits, making it ideal for high-throughput bioinformatics pipelines and automated annotation scripts.

Base URL

All requests must be made to the following base endpoint managed by our Kong API Gateway:

https://api.bioinfo.cbmeg.unicamp.br/taxonomy/

Endpoint Specification

Get Full Taxonomic Lineage

Retrieves the complete hierarchical lineage for a given identifier, organized sequentially from the most specific rank (the query target) up to the most general rank (root).

  • HTTP Method: GET
  • URL Path Parameter: {taxId} (A valid, positive non-zero integer representing the NCBI Taxonomy ID)
GET /taxonomy/{taxId}

Request Example

To retrieve the complete taxonomic lineage for Escherichia coli (TaxID: 562), you can use standard command-line tools like curl:

curl -i -X GET https://api.bioinfo.cbmeg.unicamp.br/taxonomy/562

Response Format

The API responds exclusively with a structured application/json payload containing the original query ID and an array representing the full lineage path.

Success Response (200 OK)

{
  "query_taxId": 562,
  "lineage": [
    {
      "taxId": 562,
      "scientificName": "Escherichia coli",
      "rank": "species"
    },
    {
      "taxId": 561,
      "scientificName": "Escherichia",
      "rank": "genus"
    },
    {
      "taxId": 543,
      "scientificName": "Enterobacteriaceae",
      "rank": "family"
    },
    {
      "taxId": 91347,
      "scientificName": "Enterobacterales",
      "rank": "order"
    },
    {
      "taxId": 1224,
      "scientificName": "Proteobacteria",
      "rank": "phylum"
    },
    {
      "taxId": 2,
      "scientificName": "Bacteria",
      "rank": "superkingdom"
    },
    {
      "taxId": 1,
      "scientificName": "root",
      "rank": "no rank"
    }
  ]
}

JSON Fields Breakdown

Key Type Description
query_taxId Integer The exact NCBI Taxonomic Identifier requested in the URL.
lineage Array An ordered list of ancestral nodes, starting from the requested node down to the root.
└─ taxId Integer The unique NCBI Taxonomy ID for that specific hierarchical node.
└─ scientificName String The official, curated scientific name recognized by the NCBI.
└─ rank String The taxonomic rank of the node (e.g., species, genus, family).

HTTP Status Codes & Error Handling

The API uses standard RESTful HTTP status codes to communicate request outcomes. Errors return a JSON object with descriptive messages.

400 Bad Request — Triggered if the parameter appended to the URL is missing or cannot be validated as an integer. 
{ "error": "TaxID invalido ou ausente na URL." }
404 Not Found — Returned when the requested TaxID is valid but does not exist within the local mirror database. 
{ "error": "TaxID nao localizado na base local do NCBI." }

💡 Performance and Best Practices

Because this service utilizes memory-mapped, non-blocking asynchronous database connectivity routing built straight inside the API Gateway routing layer, it can sustain massive parallel workloads. However, when parsing very large metagenomics tables or annotation logs, we highly recommend executing your pipeline loops using keep-alive persistent HTTP connections inside your scripts to minimize TLS handshake overheads.