Variant annotation service

This page describes the reference for the MyVariant.info variant annotation web service. It’s also recommended to try it live on our interactive API page.

Service endpoint

http://myvariant.info/v1/variant

GET request

Obtaining the variant annotation via our web service is as simple as calling this URL:

http://myvariant.info/v1/variant/<variantid>

variantid above is an HGVS name based variant id using genomic location based on hg19 human genome assembly.

By default, this will return the complete variant annotation object in JSON format. See here for an example and here for more details. If the input variantid is not valid, 404 (NOT FOUND) will be returned.

Optionally, you can pass a “fields” parameter to return only the annotation you want (by filtering returned object fields):

http://myvariant.info/v1/variant/chr1:g.35367G>A?fields=cadd

fields” accepts any attributes (a.k.a fields) available from the variant object. Multiple attributes should be seperated by commas. If an attribute is not available for a specific variant object, it will be ignored. Note that the attribute names are case-sensitive.

Just like the variant query service, you can also pass a “callback” parameter to make a JSONP call.

Query parameters

fields

Optional, can be a comma-separated fields to limit the fields returned from the variant object. If “fields=all”, all available fields will be returned. Note that it supports dot notation as well, e.g., you can pass “cadd.gene”. Default: “fields=all”.

callback

Optional, you can pass a “callback” parameter to make a JSONP call.

filter

Alias for “fields” parameter.

email

Optional, if you are regular users of our services, we encourage you to provide us an email, so that we can better track the usage or follow up with you.

Returned object

A GET request like this:

http://myvariant.info/v1/variant/chr1:g.35367G>A

should return a variant object below:

{
  "_id": "chr1:g.35367G>A",
  "_version": 2,
  "cadd": {
    "alt": "A",
    "annotype": "NonCodingTranscript",
    "bstatistic": 994,
    "chmm": {
      "bivflnk": 0.0,
      "enh": 0.0,
      "enhbiv": 0.0,
      "het": 0.0,
      "quies": 1.0,
      "reprpc": 0.0,
      "reprpcwk": 0.0,
      "tssa": 0.0,
      "tssaflnk": 0.0,
      "tssbiv": 0.0,
      "tx": 0.0,
      "txflnk": 0.0,
      "txwk": 0.0,
      "znfrpts": 0.0
    },
    "chrom": 1,
    "consdetail": "non_coding_exon,nc",
    "consequence": "NONCODING_CHANGE",
    "consscore": 5,
    "cpg": 0.03,
    "dna": {
      "helt": -2.04,
      "mgw": 0.01,
      "prot": 1.54,
      "roll": -0.63
    },
    "encode": {
      "exp": 31.46,
      "h3k27ac": 23.44,
      "h3k4me1": 23.8,
      "h3k4me3": 8.6
    },
    "exon": "2/3",
    "fitcons": 0.577621,
    "gc": 0.48,
    "gene": {
      "cds": {
        "cdna_pos": 476,
        "rel_cdna_pos": 0.4
      },
      "feature_id": "ENST00000417324",
      "gene_id": "ENSG00000237613",
      "genename": "FAM138A"
    },
    "gerp": {
      "n": 1.29,
      "s": -0.558
    },
    "isknownvariant": "FALSE",
    "istv": "FALSE",
    "length": 0,
    "mapability": {
      "20bp": 0,
      "35bp": 0
    },
    "min_dist_tse": 122,
    "min_dist_tss": 707,
    "mutindex": 70,
    "phast_cons": {
      "mammalian": 0.003,
      "primate": 0.013,
      "vertebrate": 0.003
    },
    "phred": 1.493,
    "phylop": {
      "mammalian": -0.155,
      "primate": 0.151,
      "vertebrate": -0.128
    },
    "pos": 35367,
    "rawscore": -0.160079,
    "ref": "G",
    "scoresegdup": 0.99,
    "segway": "D",
    "type": "SNV"
  },
  "dbnsfp": {
    "aa": {
      "aapos_sift": "ENSP00000409362:P44L",
      "alt": "L",
      "codonpos": 2,
      "pos": 44,
      "ref": "P",
      "refcodon": "CCG"
    },
    "alt": "A",
    "ancestral_allele": "G",
    "cadd": {
      "phred": 1.493,
      "raw": -0.160079,
      "raw_rankscore": 0.05963
    },
    "cds_strand": "-",
    "chrom": "1",
    "ensembl": {
      "geneid": "ENSG00000237613",
      "transcriptid": "ENST00000417324"
    },
    "fold-degenerate": 0,
    "genename": "FAM138A",
    "gerp++": {
      "nr": 1.29,
      "rs": -0.558,
      "rs_rankscore": 0.11796
    },
    "hg18": {
      "end": 25230,
      "start": 25230
    },
    "hg19": {
      "end": 35367,
      "start": 35367
    },
    "hg38": {
      "end": 35367,
      "start": 35367
    },
    "lr": {
      "pred": "T",
      "rankscore": 0.32941,
      "score": 0.0846
    },
    "mutationtaster": {
      "converted_rankscore": 0.10124,
      "pred": "N",
      "score": 1.0
    },
    "phastcons": {
      "100way": {
        "vertebrate": 0.001,
        "vertebrate_rankscore": 0.1272
      },
      "46way": {
        "placental": 0.003,
        "placental_rankscore": 0.11579,
        "primate": 0.336,
        "primate_rankscore": 0.28762
      }
    },
    "phylop": {
      "100way": {
        "vertebrate": 0.055,
        "vertebrate_rankscore": 0.14229
      },
      "46way": {
        "placental": -0.143,
        "placental_rankscore": 0.11334,
        "primate": 0.175,
        "primate_rankscore": 0.17021
      }
    },
    "provean": {
      "converted_rankscore": 0.92415,
      "pred": "D",
      "score": -6.73
    },
    "radialsvm": {
      "pred": "T",
      "rankscore": 0.32188,
      "score": -0.9916
    },
    "ref": "G",
    "reliability_index": 5,
    "sift": {
      "converted_rankscore": 0.2575,
      "pred": "T",
      "score": 0.13
    },
    "siphy_29way": {
      "logodds": 3.5364,
      "logodds_rankscore": 0.07795,
      "pi": {
        "a": 0.5429,
        "c": 0.0,
        "g": 0.4571,
        "t": 0.0
      }
    },
    "vest3": {
      "rankscore": 0.16309,
      "score": 0.137
    }
  }
}

Batch queries via POST

Although making simple GET requests above to our variant query service is sufficient in most use cases, there are some times you might find it’s easier to batch query (e.g., retrieving variant annotations for multiple variants). Fortunately, you can also make batch queries via POST requests when you need:

URL: http://myvariant.info/v1/variant
HTTP method:  POST

Query parameters

ids

Required. Accept multiple HGVS variant ids separated by comma, e.g., “ids=chr1:g.35367C>T,chr7:g.55241707G>T,chr16:g.28883241A>G”. Note that currently we only take the input ids up to 1000 maximum, the rest will be omitted.

fields

Optional, can be a comma-separated fields to limit the fields returned from the matching hits. If “fields=all”, all available fields will be returned. Note that it supports dot notation as well, e.g., you can pass “dbnsfp”, “dbnsfp.genename”, or “dbnsfp.aa.*”. Default: “all”.

email

Optional, if you are regular users of our services, we encourage you to provide us an email, so that we can better track the usage or follow up with you.

Example code

Unlike GET requests, you can easily test them from browser, make a POST request is often done via a piece of code, still trivial of course. Here is a sample python snippet:

import httplib2
h = httplib2.Http()
headers = {'content-type': 'application/x-www-form-urlencoded'}
params = 'ids=chr16:g.28883241A>G,chr1:g.35367G>A&fields=dbnsfp.genename,cadd.gene'
res, con = h.request('http://myvariant.info/v1/variant', 'POST', params, headers=headers)

Returned object

Returned result (the value of “con” variable above) from above example code should look like this:

[
  {
    "_id": "chr16:g.28883241A>G",
    "cadd": {
      "gene": {
        "ccds_id": "CCDS53996.1",
        "cds": {
          "cdna_pos": 1889,
          "cds_pos": 1450,
          "rel_cdna_pos": 0.61,
          "rel_cds_pos": 0.64
        },
        "feature_id": "ENST00000322610",
        "gene_id": "ENSG00000178188",
        "genename": "SH2B1",
        "prot": {
          "protpos": 484, "rel_prot_pos": 0.64
        }
      }
    },
    "dbnsfp": {
      "genename": "SH2B1"
    },
    "query": "chr16:g.28883241A>G"
  },
  {
    "_id": "chr1:g.35367G>A",
    "cadd": {
      "gene": {
        "cds": {
          "cdna_pos": 476,
          "rel_cdna_pos": 0.4
        },
        "feature_id": "ENST00000417324",
        "gene_id": "ENSG00000237613",
        "genename": "FAM138A"
      }
    },
    "dbnsfp": {
      "genename": "FAM138A"
    },
    "query": "chr1:g.35367G>A"
  }
]