The /taxonomicRanks API endpoint provides a dynamic list of valid taxonomic ranks present in the current taxonomy index. This endpoint is designed to serve as a single source of truth for clients that need to display, filter, or otherwise interact with taxonomic rank data in the UI or downstream scripts.

Purpose and Functionality

The endpoint aggregates unique values of the taxon_rank field from the underlying Elasticsearch index, excluding the special value "no rank". It returns up to 100 unique ranks, reflecting the taxonomy schema in use for the current result, taxonomy, or release. The endpoint's response includes a status object, an array of ranks, and the time taken to process the request. If an error occurs, the response contains an error message and an empty ranks array. The endpoint automatically reflects any upstream taxonomy schema changes, ensuring that clients always receive an up-to-date list of valid ranks for the current dataset. This is especially important for UI components such as dropdowns or filters that need to remain in sync with the taxonomy data model.

Example Request and Response

A typical request to the endpoint:

GET /api/v2/taxonomicRanks

A successful response:

{
  "status": { "success": true },
  "ranks": [
    "domain",
    "kingdom",
    "phylum",
    "class",
    "order",
    "family",
    "genus",
    "species"
    // ...additional ranks as present in the index
  ],
  "took": 12
}

If an error occurs (e.g., backend unavailable):

{
  "status": { "success": false, "error": "Internal Server error" },
  "ranks": [],
  "took": 5
}

Taxonomy Schema Change: 'superkingdom' Consolidated to 'domain'

Recent updates to the NCBI taxonomy schema moved "Eukaryota" to the "Domain" rank, consolidating the former "superkingdom" rank into "domain". This change required updates throughout the system, including the UI and reports, to reflect the new rank structure. For example, reports and UI tests that previously used "superkingdom" as a category now use "domain" instead. The /taxonomicRanks endpoint automatically reflects this change, so clients consuming this endpoint will see "domain" (and not "superkingdom") in the returned list of ranks, ensuring consistency across the application and with upstream taxonomy sources (source).

Client Usage

Clients should consume the /taxonomicRanks endpoint to dynamically populate UI elements such as dropdowns, filters, or selection lists for taxonomic ranks. This approach ensures that the UI always matches the taxonomy schema in use, even as upstream changes occur. For example, to populate a filter for available taxonomic ranks, a client can fetch the list from this endpoint and use the returned array to build the filter options. This eliminates the need for hardcoded rank lists and reduces the risk of mismatches between the UI and the underlying data.

Best Practices

• Always fetch the list of ranks from /taxonomicRanks rather than maintaining a static list in the client.
• Use the returned list to drive UI elements and filtering logic.
• Handle error responses gracefully by displaying an appropriate message or fallback UI if the ranks cannot be loaded.
• Be aware that the list of ranks may change as the taxonomy schema evolves, and design UI components to accommodate such changes.

References

• API implementation: /taxonomicRanks route handler
• Taxonomic rank aggregation logic
• Discussion of taxonomy schema changes and UI impact