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 separated 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”.
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"
}
]