Variant annotation data

Data sources

We currently obtain variant annotation data from several data resources and keep them up-to-date, so that you don’t have to do it:

* key name: this is the key for the specific annotation data in a variant object.

The most updated information can be accessed here.


Each data source may have its own usage restrictions (e.g. CADD data are free for non-commercial use only). Please refer to the data source pages above for their specific restrictions.

Variant object

Variant annotation data are both stored and returned as a variant object, which is essentially a collection of fields (attributes) and their values:

  "_id": "chr1:g.35367G>A",
  "_version": 2,
  "cadd": {
    "alt": "A",
    "annotype": "NonCodingTranscript",
    "chrom": 1,
    "gene": {
      "cds": {
        "cdna_pos": 476,
        "rel_cdna_pos": 0.4
      "feature_id": "ENST00000417324",
      "gene_id": "ENSG00000237613",
    "ref": "G",
    "type": "SNV"
  "dbnsfp": {
    "aa": {
      "aapos_sift": "ENSP00000409362:P44L",
      "alt": "L",
      "codonpos": 2,
      "pos": 44,
      "ref": "P",
      "refcodon": "CCG"
    "alt": "A",
    "ancestral_allele": "G",
    "chrom": "1",
    "ensembl": {
      "geneid": "ENSG00000237613",
      "transcriptid": "ENST00000417324"
    "genename": "FAM138A",
    "hg19": {
      "end": 35367,
      "start": 35367

The example above omits many of the available fields. For a full example, check out this example variant, or try the interactive API page.

_id field

Each individual variant object contains an “_id” field as the primary key. We utilize the recommended nomenclature from Human Genome Variation Society to define the “_id” field in Specifically, we use HGVS’s genomic reference sequence notation based on the current reference genome assembly (e.g. hg19 for human). The followings are brief representations of major types of genetic variants. More examples could be found at HVGS recommendations for the description of DNA sequence variants page.


The default reference genome assembly is always human hg19 in, so we only use “chr??” to represent the reference genomic sequence in “_id” field. The valid chromosomes representations are chr1, chr2, ..., chr22, chrX, chrY and chrMT. Do not use chr23 for chrX, chr24 for chrY, or chrM for chrMT.

  • SNV example:


    The above _id represents a C to T SNV on chromosome 1, genomic position 35366.

  • Insertion example:


    The above _id represents that an A is inserted between genomic position 17142 and 17143 on chromosome 2.

  • Deletion example:


    The above _id represents that a nine nucleotides deletion between genomic position 8271 and 8279 on chromosome MT. Note that we don’t include the deleted sequence in the _id field in this case.

  • Deletion/Insertion example:


    The above _id represents that six nucleotides between genomic position 14112 and 14117 are replaced by TG.

_score field

You will often see a “_score” field in the returned variant object, which is the internal score representing how well the query matches the returned variant object. It probably does not mean much in variant annotation service when only one variant object is returned. In variant query service, by default, the returned variant hits are sorted by the scores in descending order.

Available fields

The table below lists all of the possible fields that could be in a variant object, as well as all of their parents (for nested fields). If the field is indexed, it may also be directly queried, e.g.


All fields can be used with _exists_ or _missing_ filters, e.g.

q=_exists_:dbsnp AND _exists_:cosmic

or as inputs to the fields parameter, e.g.

Field Indexed Type Notes