NCBI Datasets API
NCBI Datasets is a resource that lets you easily gather data from NCBI. The NCBI Datasets version 2 API is updated often to add new features, fix bugs, and…
Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.
Overview
NCBI Datasets is a resource that lets you easily gather data from NCBI.
The NCBI Datasets version 2 API is updated often to add new features, fix bugs, and enhance usability.
Endpoints 111
Genome
- GETGet a download summary (preview) of a genome data package by genome assembly accession
/genome/accession/:accessions/download_summaryGet a download summary (preview) of a genome data package, including counts and file sizes, in JSON format. - POSTGet a download summary (preview) of a genome data package by genome assembly accession
/genome/download_summaryGet a downlaod summary (preview) of a genome data package, including counts and file sizes, in JSON format. - GETGet a genome assembly report by genome assembly accession
/genome/accession/:accessions/dataset_reportGet a genome assembly report by assembly accession. By default, in paged JSON format, but also available in tabular (accept: text/tab-separated-values) or… - GETGet a genome assembly report by taxon
/genome/taxon/:taxons/dataset_reportGet a genome assembly report by taxon. By default, in paged JSON format, but also available in tabular (accept: text/tab-separated-values) or JSON Lines… - GETGet genome assembly reports by BioProject accession
/genome/bioproject/:bioprojects/dataset_reportGet genome assembly reports by BioProject accession. By default, in paged JSON format, but also available in tabular (accept: text/tab-separated-values) or… - GETGet genome assembly reports by BioSample accession
/genome/biosample/:biosample_ids/dataset_reportGet genome assembly reports by BioSample accession. By default, in paged JSON format, but also available in tabular (accept: text/tab-separated-values) or… - GETGet a genome assembly data report by WGS accession
/genome/wgs/:wgs_accessions/dataset_reportGet a genome assembly data report by WGS (whole genome shotgun) accession. By default, in paged JSON format, but also available in tabular (accept:… - GETGet genome assembly reports by assembly name
/genome/assembly_name/:assembly_names/dataset_reportGet genome assembly reports by assembly name (exact matches only). By default, in paged JSON format, but also available in tabular (accept:… - POSTGet a genome assembly report
/genome/dataset_reportGet a genome assembly report. By default, in paged JSON format, but also available in tabular (accept: text/tab-separated-values) or JSON Lines (accept:… - GETGet a genome assembly accession for a nucleotide sequence accession
/genome/sequence_accession/:accession/sequence_assembliesGet a genome assembly accession for a nucleotide sequence accession in JSON format. - POSTGet a genome assembly accession for a nucleotide sequence accession
/genome/sequence_assembliesGet a genome assembly accession for a nucleotide sequence accession in JSON format. - GETGet a genome sequence report by genome assembly accession
/genome/accession/:accession/sequence_reportsGet a genome sequence report by genome assembly accession. By default, in paged JSON format, but also available in tabular (accept: text/tab-separated-values)… - POSTGet a genome sequence report by genome assembly accession
/genome/sequence_reportsGet a genome sequence report by genome assembly accession. By default, in paged JSON format, but also available in tabular (accept: text/tab-separated-values)… - GETGet assembly links by genome assembly accession
/genome/accession/:accessions/linksGet links to assembly resources by genome assembly accession in JSON format. - POSTGet assembly links by genome assembly accession
/genome/linksGet links to assembly resources by genome assembly accession in JSON format. - GETGet CheckM histogram data by species taxon
/genome/taxon/:species_taxon/checkm_histogramGet CheckM histogram data by species taxon. This data is used for rendering CheckM histograms on bacterial genome pages. - POSTGet CheckM histogram data by species taxon
/genome/checkm_histogramGet CheckM histogram data by species taxon. This data is used for rendering CheckM histograms on bacterial genome pages. - GETGet a genome data package by genome assembly accession
/genome/accession/:accessions/downloadDownload a genome data package including sequence, annotation, and a detailed data report by genome assembly accession. - POSTGet a genome data package by genome assembly accession
/genome/downloadDownload a genome data package including sequence, annotation, and a detailed data report by genome assembly accession. - GETGet a genome annotation data package by genome assembly accession
/genome/accession/:accession/annotation_report/downloadDownload an annotation data package including sequence and a detailed annotation report by genome assembly accession. - POSTGet a genome annotation data package by genome assembly accession
/genome/annotation_report/downloadDownload an annotation data package including sequence and a detailed annotation report by genome assembly accession. - GETCheck the validity of a genome assembly accession
/genome/accession/:accessions/checkCheck the validity of a genome assembly accession. Output in JSON format. - POSTCheck the validity of a genome assembly accession
/genome/checkCheck the validity of a genome assembly accession. Output in JSON format. - GETGet genome annotation reports by genome assembly accession
/genome/accession/:accession/annotation_reportGet genome annotation reports by genome assembly accession, where each report represents a single feature annotated on the genome. By default, in paged JSON… - POSTGet genome annotation reports by genome assembly accession
/genome/annotation_reportGet genome annotation reports by genome assembly accession, where each report represents a single feature annotated on the genome. By default, in paged JSON… - GETGet genome annotation report summary information by genome assembly accession
/genome/accession/:accession/annotation_summaryGet genome annotation report summary information by genome assembly accession in JSON format, including chromosome names and gene types. - POSTGet genome annotation report summary information by genome assembly accession
/genome/annotation_summaryGet genome annotation report summary information by genome assembly accession in JSON format, including chromosome names and gene types. - GETGet a download summary (preview) of a genome annotation data package by genome assembly accession
/genome/accession/:accession/annotation_report/download_summaryGet a downlaod summary (preview) of a genome annotation data package, including counts and file sizes, in JSON format. - POSTGet a download summary (preview) of a genome annotation data package by genome assembly accession
/genome/annotation_report/download_summaryGet a download summary (preview) of a genome annotation data package, including counts and file sizes, by genome assembly accession, in JSON format. - GETGet a revision history for a genome assembly by genome assembly accession
/genome/accession/:accession/revision_historyGet a revision history, or list of all versions of a genome assembly, in JSON format. - POSTGet a revision history for a genome assembly by genome assembly accession
/genome/revision_historyGet a revision history, or list of all versions of a genome assembly, in JSON format.
Gene
- GETGet a gene data package by GeneID
/gene/id/:gene_ids/downloadDownload a gene data package including sequence, annotation and data reports, as a compressed zip archive, by GeneID. - POSTGet a gene data package
/gene/downloadDownload a gene data package including sequence, annotation and data reports, as a compressed zip archive. - GETGet gene reports by GeneID
/gene/id/:gene_idsDeprecated. Get a gene summary by GeneID. By default, in paged JSON format, but also available as tabular (accept: text/tab-separated-values) or json-lines… - GETGet gene metadata by RefSeq Accession
/gene/accession/:accessionsDeprecated. Get a gene summary by RefSeq Accession. By default, in paged JSON format, but also available as tabular (accept: text/tab-separated-values) or… - GETGet gene metadata by gene symbol
/gene/symbol/:symbols/taxon/:taxonDeprecated. Get a gene summary by by gene symbol. By default, in paged JSON format, but also available as tabular (accept: text/tab-separated-values) or… - GETGet gene reports by taxonomic identifier
/gene/taxon/:taxonDeprecated. Get a gene summary for a specified NCBI Taxonomy ID or name (common or scientific). By default, in paged JSON format, but also available as… - POSTGet gene metadata as JSON
/geneDeprecated. Get a gene summary. By default, in paged JSON format, but also available as tabular (accept: text/tab-separated-values) or json-lines (accept:… - GETGet a gene data report by GeneID
/gene/id/:gene_ids/dataset_reportGet a gene data report by GeneID. By default, in paged JSON format, but also available in tabular (accept: text/tab-separated-values) or JSON Lines (accept:… - GETGet a gene data report by RefSeq nucleotide or protein accession
/gene/accession/:accessions/dataset_reportGet a gene data report by RefSeq nucleotide or protein accession. By default, in paged JSON format, but also available in tabular (accept:… - GETGet a gene data report by symbol and taxon
/gene/symbol/:symbols/taxon/:taxon/dataset_reportGet a gene data report by gene symbol and taxon. By default, in paged JSON format, but also available in tabular (accept: text/tab-separated-values) or JSON… - GETGet a gene data report by taxon
/gene/taxon/:taxon/dataset_reportGet a gene data report by taxon. By default, in paged JSON format, but also available in tabular (accept: text/tab-separated-values) or JSON Lines (accept:… - GETGet a gene data report by locus tag
/gene/locus_tag/:locus_tags/dataset_reportGet a gene data report by gene locus tag. By default, in paged JSON format, but also available in tabular (accept: text/tab-separated-values) or JSON Lines… - POSTGet a gene data report
/gene/dataset_reportGet a gene data report. By default, in paged JSON format, but also available in tabular (accept: text/tab-separated-values) or JSON Lines (accept:… - GETGet a gene product report by GeneID
/gene/id/:gene_ids/product_reportGet a gene product report by GeneID. By default, in paged JSON format, but also available in tabular (accept: text/tab-separated-values) or JSON Lines… - GETGet a gene product report by RefSeq nucleotide or protein accession
/gene/accession/:accessions/product_reportGet a gene product report by RefSeq nucleotide or protein accession. By default, in paged JSON format, but also available in tabular (accept:… - GETGet a gene product report by symbol and taxon
/gene/symbol/:symbols/taxon/:taxon/product_reportGet a gene product report by symbol and taxon. By default, in paged JSON format, but also available in tabular (accept: text/tab-separated-values) or JSON… - GETGet a gene product report by taxon
/gene/taxon/:taxon/product_reportGet a gene product report by taxon. By default, in paged JSON format, but also available in tabular (accept: text/tab-separated-values) or JSON Lines (accept:… - GETGet a gene product report by locus tag
/gene/locus_tag/:locus_tags/product_reportGet a gene product report by gene locus tag. By default, in paged JSON format, but also available in tabular (accept: text/tab-separated-values) or JSON Lines… - POSTGet a gene product report
/gene/product_reportGet a gene product report. By default, in paged JSON format, but also available in tabular (accept: text/tab-separated-values) or JSON Lines (accept:… - GETGet a download summary of a gene data package by GeneID
/gene/id/:gene_ids/download_summaryGet a download summary of a gene data package, including counts and estimated package size, in JSON format. - POSTGet a download summary of a gene data package
/gene/download_summaryGet a download summary of a gene data package, including counts and estimated package size, in JSON format. - GETGet gene counts by taxon
/gene/taxon/:taxon/countsGet gene counts by taxon in JSON format. - POSTGet gene counts by taxon
/gene/taxon/countsGet gene counts by taxon in JSON format. - GETGet a gene data report for a gene ortholog set by GeneID
/gene/id/:gene_id/orthologsGet a gene data report for a gene ortholog set by GeneID in JSON format. - POSTGet a gene data report for a gene ortholog set by GeneID
/gene/orthologsGet a gene data report for a gene ortholog set by GeneID in JSON format. - GETGet gene counts per chromosome by taxon and annotation name
/gene/taxon/:taxon/annotation/:annotation_name/chromosome_summaryGet gene counts per chromosome by taxon and annotation name in JSON format. - GETGet a gene expression report by GeneID
/gene/id/:gene_ids/expression_reportGet a gene expression report by GeneID. Gene expression values are organized by BioProject, sample group, BioSample, and SRA run. By default, in JSON format,… - POSTGet a gene expression report by GeneID
/gene/expression_reportGet a gene expression report by GeneID. Gene expression values are organized by BioProject, sample group, BioSample, and SRA run. By default, in JSON format,… - GETGet gene links by GeneID
/gene/id/:gene_ids/linksGet links to available gene resources in JSON format. - POSTGet gene links by GeneID
/gene/linksGet links to available gene resources in JSON format.
Prokaryote
- GETGet a prokaryote gene data package by RefSeq protein accession
/protein/accession/:accessions/downloadDownload a prokaryote gene data package including sequence, annotation and data reports by RefSeq non-redundant protein accession. - POSTGet a prokaryote gene data package by RefSeq protein accession
/protein/accession/downloadDownload a prokaryote gene data package including sequence, annotation and data reports by RefSeq non-redundant protein accession.
Virus
- GETGet a download summary of a virus genome data package by taxon
/virus/taxon/:taxon/genomeGet a download summary of a virus genome data package, including counts and file sizes, in JSON format. - POSTGet a download summary of a virus genome data package
/virus/genomeGet a download summary of a virus genome data package, including counts and file sizes, in JSON format. - GETGet a download summary of a SARS-CoV-2 protein data package by protein name
/virus/taxon/sars2/protein/:proteinsGet a download summary of a SARS-CoV-2 protein data package, including counts and file sizes, in JSON format. - POSTGet a download summary of a SARS-CoV-2 protein data package by protein name
/virus/taxon/sars2/proteinGet a download summary of a SARS-CoV-2 protein data package, including counts and file sizes, in JSON format. - GETGet virus genome metadata in a tabular format
/virus/taxon/:taxon/genome/tableDeprecated. Get virus genome metadata in tabular format for virus genomes by taxon. - GETGet SARS-CoV-2 protein metadata in a tabular format by protein name
/virus/taxon/sars2/protein/:proteins/tableGet SARS-CoV-2 protein metadata in a tabular format by protein name. - GETGet a virus data report by taxon
/virus/taxon/:taxon/dataset_reportGet a virus data report by taxon. By default, in paged JSON format, but also available in tabular (accept: text/tab-separated-values) or JSON Lines (accept:… - GETGet a virus data report by nucleotide accession
/virus/accession/:accessions/dataset_reportGet a virus data report by nucleotide accession. By default, in paged JSON format, but also available in tabular (accept: text/tab-separated-values) or JSON… - POSTGet a virus data report
/virusGet a virus data report. By default, in paged JSON format, but also available in tabular (accept: text/tab-separated-values) or JSON Lines (accept:… - GETGet a virus annotation report by taxon
/virus/taxon/:taxon/annotation_reportGet virus annotation report by taxon. By default, in paged JSON format, but also available in tabular (accept: text/tab-separated-values) or JSON Lines… - GETGet a virus annotation report by nucleotide accession
/virus/accession/:accessions/annotation_reportGet a virus annotation report by nucleotide accesion. By default, in paged JSON format, but also available in tabular (accept: text/tab-separated-values) or… - POSTGet a virus annotation report
/virus/annotation_reportGet a virus annotation report. By default, in paged JSON format, but also available in tabular (accept: text/tab-separated-values) or JSON Lines (accept:… - GETCheck the validity of a virus genome nucleotide accession
/virus/accession/:accessions/checkCheck the validity of a virus genome nucleotide accession. Output in JSON format. - POSTCheck the validity of a virus genome nucleotide accession
/virus/checkCheck the validity of a virus genome nucleotide accession. Output in JSON format. - GETGet a virus genome data package by taxon
/virus/taxon/:taxon/genome/downloadDownload a virus genome data package including sequence, annotation, BioSample data and a detailed data report by taxon. - GETGet a virus genome data package by nucleotide accession
/virus/accession/:accessions/genome/downloadDownload a virus genome data package including sequence, annotation, BioSample data and a detailed data report by nucleotide accession. - POSTGet a virus genome data package
/virus/genome/downloadDownload a virus genome data package including sequence, annotation, BioSample data and a detailed data report by nucleotide accession. - GETGet a SARS-CoV-2 protein data package by protein name
/virus/taxon/sars2/protein/:proteins/downloadDownload a SARS-CoV-2 protein data package including sequence, annotation, BioSample data and a detailed data report by protein name. - POSTGet a SARS-CoV-2 protein data package
/virus/taxon/sars2/protein/downloadDownload a SARS-CoV-2 protein data package including sequence, annotation, BioSample data and a detailed data report.
Version
- GETRetrieve service version
/versionRetrieve the latest version of the Datasets services.
Taxonomy
- GETGet a taxonomy data package by Taxonomy ID
/taxonomy/taxon/:tax_ids/downloadDownload a taxonomy data package, including taxonomy and names reports, as a compressed zip archive. - POSTGet a taxonomy data package by Taxonomy ID
/taxonomy/downloadDownload a taxonomy data package, including taxonomy and names reports, as a compressed zip archive. - GETUse taxonomic identifiers to get taxonomic metadata
/taxonomy/taxon/:taxonsDeprecated. Using NCBI Taxonomy IDs or names (common or scientific) at any rank, get metadata about a taxonomic node including taxonomic identifiers, lineage… - POSTGet taxonomy metadata by taxon
/taxonomyDeprecated. Get taxonomy metadata by taxon in JSON format. - GETGet a biocollection report by collection ID or code
/taxonomy/biocollections/id/:collection_ids/dataset_reportGet a biocollection report by collection ID or code in JSON format. - POSTGet a biocollection report by collection ID or code
/taxonomy/biocollections/dataset_reportGet a biocollection report by collection ID or code in JSON format. - GETGet a taxonomy data report by taxon
/taxonomy/taxon/:taxons/dataset_reportGet a taxonomy data report by taxon. By default, in paged JSON format, but also available in tabular (accept: text/tab-separated-values) or JSON Lines… - POSTGet a taxonomy data report by taxon
/taxonomy/dataset_reportGet a taxonomy data report by taxon. By default, in paged JSON format, but also available in tabular (accept: text/tab-separated-values) or JSON Lines… - GETGet a taxonomy names report by taxon
/taxonomy/taxon/:taxons/name_reportGet a taxonomy names report, including common names and other synonyms, in JSON format. - POSTGet a taxonomy names report by taxon
/taxonomy/name_reportGet a taxonomy names report, including common names and other synonyms, in JSON format. - GETGet child nodes, and optionally parent nodes, for a given taxon by Taxonomy ID
/taxonomy/taxon/:tax_id/related_idsGet child nodes, and optionally parent nodes, in JSON format. - POSTGet child nodes, and optionally parent nodes, for a given taxon by Taxonomy ID
/taxonomy/related_idsGet child nodes, and optionally parent nodes, in JSON format. - GETGet a filtered taxonomic subtree by taxon
/taxonomy/taxon/:taxons/filtered_subtreeGet a filtered taxonomic subtree, including parent and child nodes, in JSON format. - POSTGet a filtered taxonomic subtree by taxon
/taxonomy/filtered_subtreeGet a filtered taxonomic subtree, including parent and child nodes, in JSON format. - GETGet a list of taxonomy names and IDs by partial taxonomic name
/taxonomy/taxon_suggest/:taxon_queryGet a list of taxonomy names and IDs in JSON format. - POSTGet a list of taxonomy names and IDs by partial taxonomic name
/taxonomy/taxon_suggestGet a list of taxonomy names and IDs in JSON format. - GETGet external links by Taxonomy ID
/taxonomy/taxon/:taxon/linksGet external links associated with a given taxon in JSON format. - POSTGet external links by Taxonomy ID
/taxonomy/linksGet external links associated with a given taxon in JSON format. - GETGet a taxonomy image by taxon
/taxonomy/taxon/:taxon/imageGet an image associated with the specified taxon. By default, in JPEG format, but also available in PNG (accept: image/png), TIFF (accept: accept:… - POSTGet a taxonomy image by taxon
/taxonomy/imageGet an image associated with the specified taxon. By default, in JPEG format, but also available in PNG (accept: image/png), TIFF (accept: accept:… - GETGet taxonomy image metadata by Taxonomy ID
/taxonomy/taxon/:taxon/image/metadataGet taxonomy image metadata, including the image URL and license information, in JSON format. - POSTGet taxonomy image metadata by Taxonomy ID
/taxonomy/image/metadataGet taxonomy image metadata, including the image URL and license information, in JSON format.
BioSample
- GETGet BioSample dataset reports by accession(s)
/biosample/accession/:accessions/biosample_reportGet BioSample dataset reports by accession(s). By default, in paged JSON format, but also available as tabular (accept: text/tab-separated-values) or…
Organelle
- GETGet an organelle data package by nucleotide accession
/organelle/accession/:accessions/downloadDownload an organelle data package including sequence, annotation, and detailed data reports as a compressed zip archive. - POSTGet an organelle data package
/organelle/downloadDownload an organelle data package including sequence, annotation, and detailed data reports as a compressed zip archive. - GETGet an organelle data report by nucleotide accession
/organelle/accessions/:accessions/dataset_reportGet an organelle data report in JSON format. - GETGet an organelle data report by taxon
/organelle/taxon/:taxons/dataset_reportGet an organelle data report in JSON format. - POSTGet an organelle data report
/organelle/dataset_reportGet an organelle data report in JSON format.
API details
- Base URL
https://api.ncbi.nlm.nih.gov/datasets/v2- Authentication
- An API key in the api_key query parameter
An API key in the api-key header - Operations
- 111 operations on 111 pathsGET 68POST 43
8 marked deprecated - Main resources
- Genome 31Gene 30Taxonomy 22Virus 19Organelle 5Prokaryote 2BioSample 1Version 1
- Response formats
text/plainapplication/jsontext/tab-separated-valuesapplication/x-ndjson- Description format
- OpenAPI 3.0.1, API version
v2 - Links
- Documentation · OpenAPI document
- Listed from
- NCBI (NIH)'s published OpenAPI description (ncbi/datasets) (Public-Domain (US Government Work))
How to test the NCBI Datasets API in Swastik Codes
- Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
- Fork it into your workspaceChoose a workspace. You get your own copy of the NCBI Datasets API collection, without the publisher's secrets.
- Add your credentialsThis API uses an API key in the api_key query parameter. Add yours in the collection's variables or an environment; the requests already reference it.
- Send a requestPick an endpoint, for example “Get a download summary (preview) of a genome data package by genome assembly accession” (GET /genome/accession/:accessions/download_summary), and press Send. Check the response, add tests and run the whole collection with the runner.
Frequently asked questions
What is the NCBI Datasets API?
NCBI Datasets is a resource that lets you easily gather data from NCBI. The NCBI Datasets version 2 API is updated often to add new features, fix bugs, and… It is listed under Data & analytics and has 111 endpoints.
Who publishes the NCBI Datasets API?
It is listed from NCBI (NIH)'s public API description (an OpenAPI document), not published by NCBI (NIH) on Swastik Codes. Anyone who controls nih.gov can claim the profile by adding a DNS TXT record.
What is the base URL of the NCBI Datasets API?
Requests go to https://api.ncbi.nlm.nih.gov/datasets/v2. Endpoint paths are added to this base URL.
How do I authenticate with the NCBI Datasets API?
It accepts 2 methods: an API key in the api_key query parameter; an API key in the api-key header.
How many endpoints does the NCBI Datasets API have?
111 operations on 111 paths (68 GET, 43 POST). The largest groups are Genome, Gene, Taxonomy, Virus.
Is forking the NCBI Datasets API free?
Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.