NCncats
Taxonomy

Use taxonomic identifiers to get taxonomic metadata

Changed on

Using NCBI Taxonomy IDs or names (common or scientific) at any rank, get metadata about a taxonomic node including taxonomic identifiers, lineage information, child nodes, and gene and genome counts in JSON format.

get/taxonomy/taxon/{taxons}

Request

  • Base URL
    https://api.ncbi.nlm.nih.gov/datasets/v2
  • Auth
    API key in header api-key

Path parameters

taxonsstring[] required

Query parameters

returned_content'COMPLETE' | 'TAXIDS' | 'METADATA'

Return complete taxonomy reports, Taxonomy IDs only, or reports without assembly and gene counts (metadata).

page_sizeinteger

The maximum number of taxons to return. Default is 20 and maximum is 1000. If the number of results exceeds the page size, page_token can be used to retrieve the remaining results.

include_tabular_header'INCLUDE_TABULAR_HEADER_FIRST_PAGE_ONLY' | 'INCLUDE_TABULAR_HEADER_ALWAYS' | 'INCLUDE_TABULAR_HEADER_NEVER'

Specify when to include the table header when requesting a tabular report.

page_tokenstring

A page token is returned when the results count exceeds page size. Use this token along with previous request parameters to retrieve the next page of results. When page_token is empty, all results have been retrieved.

table_format'SUMMARY'

Specify a predefined set of fields for the tabular report using built-in templates. Use of this parameter requires the HTTP header, accept: text/tab-separated-values.

childrenboolean

If true, return results for child taxa.

ranksV2reportsRankType[]

Limit results to taxa of the specified ranks.

Response

A successful response

Changes

  • e5d4400c8e5dRevision changes
    • info

      endpoint deprecated

    • info

      added the optional property /// to the response with the status

    • info

      added the optional property //// to the response with the status

  • 6b24249801ecRevision changes
    • breaking

      for the query request parameter include_tabular_header, default value INCLUDE_TABULAR_HEADER_FIRST_PAGE_ONLY was added

    • breaking

      for the query request parameter returned_content, default value COMPLETE was added

    • breaking

      for the query request parameter table_format, default value SUMMARY was added

    • info

      the response's property default value UNKNOWN_ASSEMBLY_ERROR_CODE was added for the status

    • info

      the response's property default value UNKNOWN_ASSEMBLY_ERROR_CODE was added for the status

    • info

      the response's property default value UNKNOWN_GENE_ERROR_CODE was added for the status

    • info

      the response's property default value UNKNOWN_GENE_ERROR_CODE was added for the status

    • info

      the response's property default value UNKNOWN_GENE_WARNING_CODE was added for the status

    • info

      the response's property default value UNKNOWN_GENE_WARNING_CODE was added for the status

    • info

      the response's property default value UNKNOWN_ORGANELLE_ERROR_CODE was added for the status

    • info

      the response's property default value UNKNOWN_ORGANELLE_ERROR_CODE was added for the status

    • info

      the response's property default value NO_RANK was added for the status

    • info

      the response's property default value UNKNOWN_TAXONOMY_ERROR_CODE was added for the status

    • info

      the response's property default value UNKNOWN_TAXONOMY_ERROR_CODE was added for the status

    • info

      the response's property default value COUNT_TYPE_UNSPECIFIED was added for the status

    • info

      the response's property default value UNKNOWN_VIRUS_ERROR_CODE was added for the status

    • info

      the response's property default value UNKNOWN_VIRUS_ERROR_CODE was added for the status