last update

2026-July-13

VirJenDB

v1.0

VirJenDB API

VirJenDB provides a public API that allows you to search virus records, retrieve genome sequences, inspect metadata fields, and download datasets programmatically.

The API is intended for:

• automated analysis workflows
• external web applications
• bioinformatics pipelines
• bulk data retrieval
• metadata exploration

The API uses JSON request bodies and standard HTTP methods.

Getting Started

The VirJenDB API base URL is:

https://api2.virjendb.org

Interactive Swagger documentation is available at:

https://api2.virjendb.org/swagger

At the time of writing, the public API does not require authentication.

Available Endpoints

Searching Records

One of the main features of the VirJenDB API is the /v2/search endpoint. It uses the same underlying search backend as the VirJenDB web interface.

Endpoint

POST /v2/search

Basic Search

This description is outdated an will be re-written, soon.

Search Response

Example responses may vary depending on the selected metadata fields and database version.

{
  "total": 1244169,
  "results": [
    {
      "source": {
        "Organism Name": "Influenza A virus",
        "NCBI Species": "Alphainfluenzavirus influenzae",
        "Host Species": "Homo sapiens",
        "Country": "China",
        "Collection Date": "2017-06-30"
      }
    }
  ]
}

Search Clauses

This description is outdated an will be re-written, soon.

Search Multiple Conditions

This description is outdated an will be re-written, soon.

Search Operators

This description is outdated an will be re-written, soon.

Pagination

Search results are paginated.

Example:

{
  "pageSize": 100,
  "pageNumber": 2
}

This returns the second page of results containing up to 100 entries. For best performance, avoid excessively large page sizes.

Note: The VirJenDB search results page can only paginate through the first 10,000 matching entries. To inspect additional matches, narrow the search query or apply filters so the relevant records fall within that range.

Sorting Results

Search results can be sorted using sortColumn and sortOrder.

Example:

{
  "sortColumn": "Collection Date",
  "sortOrder": "desc"
}

Supported sort directions are:

• asc
• desc

Example Search Request

This description is outdated an will be re-written, soon.

curl -X POST "https://api2.virjendb.org/v2/search" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "metadataField": "Host Species",
        "searchTerm": "Homo sapiens"
      }
    ],
    "filter": [],
    "pageSize": 20,
    "pageNumber": 1,
    "sortOrder": "asc"
  }'

Downloading Records

The /v2/download endpoint allows you to export metadata, accession IDs, or genome sequences.

Endpoint

POST /v2/download

Information Types

The information parameter controls what type of data is downloaded.

Output Formats

The fileType parameter controls the output format.

FASTA output is only available when downloading sequences.

Download Scope

The scope parameter controls which records are included in the download.

Download Matching Search Results

This description is outdated an will be re-written, soon.

The following request downloads metadata records matching a search query.

{
  "download": {
    "scope": "max",
    "information": "metadata",
    "fileType": "csv",
    "metadata": [
      "Organism Name",
      "Host Species",
      "Collection Date"
    ]
  },
  "search": {
    "items": [
      {
        "metadataField": "Molecule Type",
        "searchTerm": "ssRNA(+)"
      }
    ],
    "pageSize": 1000,
    "pageNumber": 1,
    "sortOrder": "asc"
  }
}

This downloads metadata for all records matching the specified search query.

Download Selected Records

This description is outdated an will be re-written, soon.

Instead of downloading all matching search results, you can explicitly provide accession IDs.

Example:

{
  "download": {
    "scope": "selection",
    "information": "metadata",
    "fileType": "csv",
    "selected_ids": [
      "vj000000000010",
      "vj000005747069"
    ]
  }
}

VirJenDB accession IDs follow the format:

vj000000000010

Selection downloads currently support up to 10,000 accession IDs per request.

Downloading Sequences

This description is outdated an will be re-written, soon.

Sequences can be downloaded using:

{
  "download": {
    "scope": "selection",
    "information": "sequences",
    "fileType": "fasta",
    "metadata": [
      "Host Species",
      "Molecule Type"
    ],
    "selected_ids": [
      "vj000000000010"
    ]
  }
}

When exporting sequences in FASTA format:

• sequence data is returned in FASTA format
• metadata fields may be added to FASTA headers
• fields are separated using the | character
• the VirJenDB accession is always included in the header

Example:

>vj000000000010|Host Species=Homo sapiens|Molecule Type=ssRNA(+)
AUGCUAGCUAGCUAGCUAGC

Retrieving Sequences

The /v2/sequence endpoint retrieves sequences directly from VirJenDB accession IDs.

Endpoint

POST /v2/sequence

Example Request

{
  "virjendb_accessions": [
    "vj000000000010",
    "vj000005747069"
  ]
}

Notes

• accession IDs must follow the VirJenDB accession format
• sequence formatting may vary depending on the requested records
• response structures may evolve between database versions

Downloading Precomputed Datasets

VirJenDB provides pre-generated datasets for bulk download through the /v2/datasets_download endpoint.

Endpoint

GET /v2/datasets_download

Download a Dataset

Datasets are selected using the required filename query parameter. Use one of the dataset filenames listed below.

Example:

GET /v2/datasets_download?filename=virjendbv1_full_dataset_sequence.csv.gz

Command-line examples

Metadata Datasets

curl 'https://api.virjendb.org/v2/datasets_download?filename=virjendbv1_full_dataset_metadata.csv.gz' \
  -o virjendbv1_full_dataset_metadata.csv.gz

curl 'https://api.virjendb.org/v2/datasets_download?filename=virjendbv1_unique_seqs_metadata.csv.gz' \
  -o virjendbv1_unique_seqs_metadata.csv.gz

curl 'https://api.virjendb.org/v2/datasets_download?filename=virjendbv1_votu_clusters_metadata.csv.gz' \
  -o virjendbv1_votu_clusters_metadata.csv.gz

wget -c 'https://api.virjendb.org/v2/datasets_download?filename=virjendbv1_full_dataset_metadata.csv.gz' \
  -O virjendbv1_full_dataset_metadata.csv.gz

wget -c 'https://api.virjendb.org/v2/datasets_download?filename=virjendbv1_unique_seqs_metadata.csv.gz' \
  -O virjendbv1_unique_seqs_metadata.csv.gz

wget -c 'https://api.virjendb.org/v2/datasets_download?filename=virjendbv1_votu_clusters_metadata.csv.gz' \
  -O virjendbv1_votu_clusters_metadata.csv.gz

Sequence Datasets

curl 'https://api.virjendb.org/v2/datasets_download?filename=virjendbv1_full_dataset_sequence.csv.gz' \
  -o virjendbv1_full_dataset_sequence.csv.gz

curl 'https://api.virjendb.org/v2/datasets_download?filename=virjendbv1_unique_seqs_sequence.csv.gz' \
  -o virjendbv1_unique_seqs_sequence.csv.gz

curl 'https://api.virjendb.org/v2/datasets_download?filename=virjendbv1_votu_clusters_sequence.csv.gz' \
  -o virjendbv1_votu_clusters_sequence.csv.gz

wget -c 'https://api.virjendb.org/v2/datasets_download?filename=virjendbv1_full_dataset_sequence.csv.gz' \
  -O virjendbv1_full_dataset_sequence.csv.gz

wget -c 'https://api.virjendb.org/v2/datasets_download?filename=virjendbv1_unique_seqs_sequence.csv.gz' \
  -O virjendbv1_unique_seqs_sequence.csv.gz

wget -c 'https://api.virjendb.org/v2/datasets_download?filename=virjendbv1_votu_clusters_sequence.csv.gz' \
  -O virjendbv1_votu_clusters_sequence.csv.gz

Cluster Comparison Metrics

curl 'https://api.virjendb.org/v2/datasets_download?filename=virjendbv1_votu_cluster_comparison_metrics.csv.gz' \
  -o virjendbv1_votu_cluster_comparison_metrics.csv.gz

wget -c 'https://api.virjendb.org/v2/datasets_download?filename=virjendbv1_votu_cluster_comparison_metrics.csv.gz' \
  -O virjendbv1_votu_cluster_comparison_metrics.csv.gz

Mapping Files

curl 'https://api.virjendb.org/v2/datasets_download?filename=ncbi_to_gtdb_map.csv.gz' \
  -o ncbi_to_gtdb_map.csv.gz

wget -c 'https://api.virjendb.org/v2/datasets_download?filename=ncbi_to_gtdb_map.csv.gz' \
  -O ncbi_to_gtdb_map.csv.gz

Checksum Files

SHA256 checksum files are available for downloadable datasets. They use the same /v2/datasets_download endpoint, with the checksum filename passed as the filename value.

Example:

curl 'https://api.virjendb.org/v2/datasets_download?filename=ncbi_to_gtdb_map.csv.gz' \
  -o ncbi_to_gtdb_map.csv.gz

curl 'https://api.virjendb.org/v2/datasets_download?filename=ncbi_to_gtdb_map.sha256' \
  -o ncbi_to_gtdb_map.sha256

Verify the downloaded file:

sha256sum ncbi_to_gtdb_map.csv.gz
cat ncbi_to_gtdb_map.sha256

Compare the SHA256 value printed by sha256sum with the expected value in the .sha256 file. If the two values match exactly, the file was downloaded successfully.

On macOS, use shasum -a 256 instead of sha256sum.

Notes

• Dataset files are gzip-compressed archives with the .csv.gz extension.
• Some sequence datasets are very large; use wget -c for resumable downloads.
• Checksum files can be used to verify file integrity after download.
• The VirJenDB Datasets page provides dataset descriptions, version numbers, update dates, file sizes, download commands, and SHA256 values.

Query Metadata Fields

Endpoint

POST /v2/metadata

Example Request

{
  "field_name": [],
  "privacy": [],
  "tags": [],
  "submission_requiredness": [],
  "submission_fieldtype": [],
  "submission_validation": [],
  "match_mode": "and",
  "summary": false
}

Metadata Filters

Metadata definitions may evolve between database releases.

Export Metadata Definitions

Metadata definitions can also be downloaded directly.

Endpoint

POST /v2/metadata_download

Example Request

{
  "field_name": [],
  "file_type": "csv"
}

Notes

Common export formats include:

• csv
• json
• xlsx

This endpoint can be used to export metadata field documentation and schema information.

Validation Errors

Most validation errors return HTTP status code 422.

Example:

{
  "detail": [
    {
      "loc": ["body", "items", 0],
      "msg": "field required",
      "type": "value_error"
    }
  ]
}

Additional Notes

• Very large downloads may take additional time to generate and stream data
• API response structures may evolve between database releases
• Checksum files can be used to verify dataset downloads
• The Swagger interface provides the complete OpenAPI schema