Skills › Scientific Agent Skills › database-lookup › ncbi-taxonomy.md

ncbi-taxonomy.md

123 lines · skills/database-lookup/references/ncbi-taxonomy.md at 5f2bc03

1# NCBI Taxonomy API Reference

NCBI Taxonomy API Reference

3## Overview

4Taxonomic classification data (names, lineages, ranks) for all organisms in NCBI databases. Accessible via E-utilities with `db=taxonomy`.

Overview

Taxonomic classification data (names, lineages, ranks) for all organisms in NCBI databases. Accessible via E-utilities with db=taxonomy.

Raw lines 3 to 5

6## Base URL

7```

8https://eutils.ncbi.nlm.nih.gov/entrez/eutils/

9```

Base URL

https://eutils.ncbi.nlm.nih.gov/entrez/eutils/

Raw lines 6 to 10

11## Authentication

12- **API key** (recommended): Append `&api_key=YOUR_KEY` (register at ncbi.nlm.nih.gov/account).

13- Without key: 3 req/sec. With key: 10 req/sec.

14- Provide `tool` and `email` parameters.

Authentication

API key (recommended): Append &api_key=YOUR_KEY (register at ncbi.nlm.nih.gov/account).
Without key: 3 req/sec. With key: 10 req/sec.
Provide tool and email parameters.

Raw lines 11 to 15

16## Key Endpoints

Key Endpoints

Raw lines 16 to 17

18### 1. ESearch -- Search taxonomy by name

19```

20GET esearch.fcgi?db=taxonomy&term=QUERY&retmode=json

21```

22| Param | Description |

23|-------|-------------|

24| `term` | Organism name, common name, or taxid. Fields: `[Scientific Name]`, `[Common Name]`, `[All Names]`, `[Rank]` |

25| `retmax` | Max IDs returned (default 20) |

27**Example -- search by scientific name:**

28```

29GET esearch.fcgi?db=taxonomy&term=Homo+sapiens[Scientific Name]&retmode=json

30```

31Response:

32```json

33{

34 "esearchresult": {

35 "count": "1",

36 "idlist": ["9606"]

37 }

38}

39```

41**Example -- search by common name:**

42```

43GET esearch.fcgi?db=taxonomy&term=dog[Common Name]&retmode=json

44```

1. ESearch -- Search taxonomy by name

GET esearch.fcgi?db=taxonomy&term=QUERY&retmode=json

Param	Description
`term`	Organism name, common name, or taxid. Fields: `[Scientific Name]`, `[Common Name]`, `[All Names]`, `[Rank]`
`retmax`	Max IDs returned (default 20)

Example -- search by scientific name:

GET esearch.fcgi?db=taxonomy&term=Homo+sapiens[Scientific Name]&retmode=json

Response:

{
  "esearchresult": {
    "count": "1",
    "idlist": ["9606"]
  }
}

Example -- search by common name:

GET esearch.fcgi?db=taxonomy&term=dog[Common Name]&retmode=json

Raw lines 18 to 45

46### 2. EFetch -- Retrieve full taxonomy records

47```

48GET efetch.fcgi?db=taxonomy&id=TAXIDS&retmode=xml

49```

50Note: Taxonomy EFetch only supports XML output.

52**Example -- fetch human taxonomy (taxid 9606):**

53```

54GET efetch.fcgi?db=taxonomy&id=9606&retmode=xml

55```

56Response (abbreviated XML):

57```xml

58<TaxaSet>

59 <Taxon>

60 <TaxId>9606</TaxId>

61 <ScientificName>Homo sapiens</ScientificName>

62 <OtherNames>

63 <CommonName>human</CommonName>

64 </OtherNames>

65 <Rank>species</Rank>

66 <Division>Primates</Division>

67 <GeneticCode><GCId>1</GCId><GCName>Standard</GCName></GeneticCode>

68 <MitoGeneticCode><MGCId>2</MGCId><MGCName>Vertebrate Mitochondrial</MGCName></MitoGeneticCode>

69 <Lineage>cellular organisms; Eukaryota; Opisthokonta; Metazoa; ... ; Hominidae; Homo</Lineage>

70 <LineageEx>

71 <Taxon><TaxId>131567</TaxId><ScientificName>cellular organisms</ScientificName><Rank>no rank</Rank></Taxon>

72 <Taxon><TaxId>2759</TaxId><ScientificName>Eukaryota</ScientificName><Rank>superkingdom</Rank></Taxon>

73

74 </LineageEx>

75 </Taxon>

76</TaxaSet>

77```

2. EFetch -- Retrieve full taxonomy records

GET efetch.fcgi?db=taxonomy&id=TAXIDS&retmode=xml

Note: Taxonomy EFetch only supports XML output.

Example -- fetch human taxonomy (taxid 9606):

GET efetch.fcgi?db=taxonomy&id=9606&retmode=xml

Response (abbreviated XML):

<TaxaSet>
  <Taxon>
    <TaxId>9606</TaxId>
    <ScientificName>Homo sapiens</ScientificName>
    <OtherNames>
      <CommonName>human</CommonName>
    </OtherNames>
    <Rank>species</Rank>
    <Division>Primates</Division>
    <GeneticCode><GCId>1</GCId><GCName>Standard</GCName></GeneticCode>
    <MitoGeneticCode><MGCId>2</MGCId><MGCName>Vertebrate Mitochondrial</MGCName></MitoGeneticCode>
    <Lineage>cellular organisms; Eukaryota; Opisthokonta; Metazoa; ... ; Hominidae; Homo</Lineage>
    <LineageEx>
      <Taxon><TaxId>131567</TaxId><ScientificName>cellular organisms</ScientificName><Rank>no rank</Rank></Taxon>
      <Taxon><TaxId>2759</TaxId><ScientificName>Eukaryota</ScientificName><Rank>superkingdom</Rank></Taxon>
      <!-- ... each ancestor node ... -->
    </LineageEx>
  </Taxon>
</TaxaSet>

Raw lines 46 to 78

79### 3. ESummary -- Brief taxonomy summaries

80```

81GET esummary.fcgi?db=taxonomy&id=TAXIDS&retmode=json

82```

83**Example -- multiple taxa:**

84```

85GET esummary.fcgi?db=taxonomy&id=9606,10090,7227&retmode=json

86```

87Response includes: lowercase JSON keys `scientificname`, `commonname`, `rank`, `division`, `taxid`, `genus`, `species` (XML uses different capitalization).

3. ESummary -- Brief taxonomy summaries

GET esummary.fcgi?db=taxonomy&id=TAXIDS&retmode=json

Example -- multiple taxa:

GET esummary.fcgi?db=taxonomy&id=9606,10090,7227&retmode=json

Response includes: lowercase JSON keys scientificname, commonname, rank, division, taxid, genus, species (XML uses different capitalization).

Raw lines 79 to 88

89### 4. ELink -- Cross-link taxonomy to other databases

90```

91GET elink.fcgi?dbfrom=taxonomy&db=protein&id=9606&term=insulin

92```

93Find all protein records for a given taxid, optionally filtered by keyword.

4. ELink -- Cross-link taxonomy to other databases

GET elink.fcgi?dbfrom=taxonomy&db=protein&id=9606&term=insulin

Find all protein records for a given taxid, optionally filtered by keyword.

Raw lines 89 to 94

95## Common Search Patterns

96```

97# All species under a genus

98term=Drosophila[Next Level] AND species[Rank]

100# Search Taxonomy by taxid directly

101term=9606[Taxonomy ID]

102

103# By rank

104term=Mammalia[Scientific Name] AND class[Rank]

105

106# Taxonomy subtree search

107term=9605[Subtree]

108```

109

110`txid9606[Organism:exp]` is a sequence-database search expression, not a Taxonomy field. Discover Taxonomy search fields with `einfo.fcgi?db=taxonomy&retmode=json`; resolve scientific names to taxids before subtree searches.

111

Common Search Patterns

# All species under a genus
term=Drosophila[Next Level] AND species[Rank]

# Search Taxonomy by taxid directly
term=9606[Taxonomy ID]

# By rank
term=Mammalia[Scientific Name] AND class[Rank]

# Taxonomy subtree search
term=9605[Subtree]

txid9606[Organism:exp] is a sequence-database search expression, not a Taxonomy field. Discover Taxonomy search fields with einfo.fcgi?db=taxonomy&retmode=json; resolve scientific names to taxids before subtree searches.

Raw lines 95 to 111

112## Useful Cross-references

113| Link | Description |

114|------|-------------|

115| `taxonomy_protein` | All proteins for a taxon |

116| `taxonomy_gene` | All genes for a taxon |

117| `taxonomy_nuccore` | All nucleotide records for a taxon |

118| `taxonomy_genome` | Genome assemblies for a taxon |

119

Useful Cross-references

Link	Description
`taxonomy_protein`	All proteins for a taxon
`taxonomy_gene`	All genes for a taxon
`taxonomy_nuccore`	All nucleotide records for a taxon
`taxonomy_genome`	Genome assemblies for a taxon

Raw lines 112 to 119

120## Rate Limits

121- Without API key: 3 requests/second

122- With API key: 10 requests/second

123- EFetch supports multiple taxids in a single call (comma-separated)

Rate Limits

Without API key: 3 requests/second
With API key: 10 requests/second
EFetch supports multiple taxids in a single call (comma-separated)

Raw lines 120 to 123