NCncats
Virus

Get a virus data report by taxon

Changed on

Get 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: application/x-ndjson) formats.

get/virus/taxon/{taxon}/dataset_report

Request

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

Path parameters

taxonstring required

NCBI Taxonomy ID or name (common or scientific) at any taxonomic rank

Query parameters

filter.refseq_onlyboolean

If true, limit results to RefSeq genomes.

filter.annotated_onlyboolean

If true, limit results to annotated genomes.

filter.released_sincestring date-time
filter.updated_sincestring date-time
filter.hoststring

Limit to genomes isolated from the specified host species (NCBI Taxonomy ID, common or scientific name).

filter.pangolin_classificationstring

Limit to SARS-CoV-2 genomes from the specified Pango lineage.

filter.geo_locationstring

Limit to genomes collected from the specified geographic location.

filter.usa_statestring

Limit to genomes collected from the specified U.S. state (two-letter abbreviation).

filter.complete_onlyboolean

Limit to genomes designated as complete, as defined by the submitter.

returned_content'COMPLETE' | 'ACCESSIONS_ONLY'

Return complete virus reports or nucleotide accessions only

table_fieldsstring[]

Specify which fields to include in the tabular report

page_sizeinteger

The maximum number of virus data reports 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.

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.

Response

A successful response

total_countinteger
next_page_tokenstring

Changes

  • 6b24249801ecRevision changes
    • breaking

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

    • info

      the response's property default value UNKNOWN was added for the status (media type: application/json)

    • info

      the response's property default value UNKNOWN was added for the status (media type: application/x-ndjson)

    • info

      the response's property default value none was added for the status (media type: application/json)

    • info

      the response's property default value none was added for the status (media type: application/x-ndjson)

    • info

      the response's property default value PURPOSE_OF_SAMPLING_UNKNOWN was added for the status (media type: application/json)

    • info

      the response's property default value PURPOSE_OF_SAMPLING_UNKNOWN was added for the status (media type: application/x-ndjson)

  • f08be9b66e16Revision changes
    • breaking

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

    • info

      added the optional property // to the response with the status (media type: application/json)

    • info

      added the optional property // to the response with the status (media type: application/x-ndjson)

    • info

      the response's property default value UNKNOWN was removed for the status (media type: application/json)

    • info

      the response's property default value UNKNOWN was removed for the status (media type: application/x-ndjson)

    • info

      the response's property default value none was removed for the status (media type: application/json)

    • info

      the response's property default value none was removed for the status (media type: application/x-ndjson)

    • info

      the response's property default value PURPOSE_OF_SAMPLING_UNKNOWN was removed for the status (media type: application/json)

    • info

      the response's property default value PURPOSE_OF_SAMPLING_UNKNOWN was removed for the status (media type: application/x-ndjson)