POST vep/:species/hgvs

Fetch variant consequences for multiple HGVS notations



NameTypeDescriptionDefaultExample Values
species String Species name/alias - homo_sapiens


NameTypeDescriptionDefaultExample Values
AncestralAllele Boolean Retrieves the ancestral allele for variants inferred from the Ensembl Compara Enredo-Pecan-Ortheus (EPO) pipeline (plugin details) 0 -
Blosum62 Boolean Include BLOSUM62 amino acid conservation score (plugin details) 0 -
CADD Boolean Include CADD (Combined Annotation Dependent Depletion) deleteriousness scores for single nucleotide variants. See license. (plugin details) 0 -
DisGeNET Boolean Retrieves Variant-Disease-PMID associations from the DisGeNET database (plugin details) 0 -
EVE Boolean EVE (evolutionary model of variant effect) is a computational method for the classification of human genetic variants trained solely on evolutionary sequences. See license. (plugin details) 0 -
Enformer Boolean Predictions of variant impact on gene expression 0 -
GO Boolean Retrieves Gene Ontology terms associated with transcripts/translations 0 -
GeneSplicer Boolean Detects splice sites in genomic DNA (plugin details) 0 -
Geno2MP Boolean Geno2MP is a web-accessible database of rare variant genotypes linked to individual-level phenotypic profiles defined by human phenotype ontology (HPO) terms (plugin details) 0 -
IntAct Boolean Provides molecular interaction data for variants as reported by IntAct database. (plugin details) - -
LoF Boolean LOFTEE identifies LoF (loss-of-function) variation. See README for more details. 0 -
Mastermind Boolean Variants that have clinical evidence cited in the medical literature reported by Mastermind Genomic Search Engine (plugin details) 0 -
MaveDB Boolean Provides scores from Multiplexed Assays of Variant Effect for variants as reported by MaveDB database. (plugin details) 0 -
MaxEntScan Boolean Sequence motif and maximum entropy based splice site consensus predictions (plugin details) 0 -
NMD Boolean Predicts if a variant allows the transcript escape nonsense-mediated mRNA decay. (plugin details) 0 -
OpenTargets Boolean Reports locus-to-gene (L2G) scores to predict causal genes at GWAS loci from Open Targets Genetics. (plugin details) 0 -
Phenotypes Boolean Retrieves overlapping phenotype information (plugin details) 0 -
SpliceAI Integer Retrieves pre-calculated annotations from SpliceAI a deep neural network, developed by Illumina, Inc that predicts splice junctions from an arbitrary pre-mRNA transcript sequence. Used for non-commercial purposes. (plugin details)
The pre-calculated annotations for all possible single nucleotide substitutions can be retrieved from: value 1) Ensembl/GENCODE v24 canonical transcripts (masked scores); value 2) Ensembl/GENCODE v37 MANE transcripts (raw scores).
Note: The pre-calculated annotations for 1 base insertions, and 1-4 base deletions are only available for Ensembl/GENCODE v24 canonical transcripts.
0 2
UTRAnnotator Boolean Annotates high-impact five prime UTR variants either creating new upstream ORFs or disrupting existing upstream ORFs (plugin details) 0 -
ambiguous_hgvs Boolean Allow input HGVSp to resolve to all genomic locations. Otherwise, most likely transcript will be selected. 0 -
appris Boolean Include APPRIS isoform annotation 0 -
callback String Name of the callback subroutine to be returned by the requested JSONP response. Required ONLY when using JSONP as the serialisation method. Please see the user guide. - randomlygeneratedname
canonical Boolean Include a flag indicating the canonical transcript for a gene 0 -
ccds Boolean Include CCDS transcript identifiers 0 -
dbNSFP String Comma-separated list of fields from dbNSFP, a database of pathogenicity predictions for missense variants. See dbNSFP README for field list or include all fields with ALL; this fetches a large amount of data per variant! By default, some fields contain values for all Ensembl transcripts; add transcript_match=1 to only return values for the matched Ensembl transcript. (plugin details) Not used LRT_pred,MutationTaster_pred
dbscSNV Boolean Predictions for splicing variants from dbscSNV. (plugin details) 0 -
distance Integer Change the distance to transcript for which VEP assigns upstream and downstream consequences 5000 -
domains Boolean Include names of overlapping protein domains 0 -
failed Boolean When checking for co-located variants, by default variants flagged as failed by Ensembl's QC pipeline will be excluded. Set this flag to 1 to include such variants 0 -
flag_pick Boolean As per pick, but adds the PICK flag to the chosen block of consequence data and retains others. 0 -
flag_pick_allele Boolean As per pick_allele, but adds the PICK flag to the chosen block of consequence data and retains others. 0 -
flag_pick_allele_gene Boolean As per pick_allele_gene, but adds the PICK flag to the chosen block of consequence data and retains others. 0 -
ga4gh_vrs Boolean Add GA4GH Variation Representation Specification (VRS) notation 0 -
gencode_basic Boolean Limit your analysis to transcripts belonging to the GENCODE basic set. This set has fragmented or problematic transcripts removed. 0 -
hgvs Boolean Include HGVS nomenclature based on Ensembl stable identifiers 0 -
mane Boolean Include MANE Select annotations (GRCh38 only) 0 -
merged Boolean Use merged Ensembl and RefSeq transcript set to report consequences (human only) 0 -
minimal Boolean Convert alleles to their most minimal representation before consequence calculation i.e. sequence that is identical between each pair of reference and alternate alleles is trimmed off from both ends, with coordinates adjusted accordingly. Note this may lead to discrepancies between input coordinates and coordinates reported by VEP relative to transcript sequences 0 -
mirna Boolean Determines where in the secondary structure of a miRNA a variant falls 0 -
mutfunc Boolean Predicts destabilization effect of protein structure, interaction, regulatory region etc. caused by a variant as reported by mutfunc database. (plugin details) 0 -
numbers Boolean Include affected exon and intron positions within the transcript 0 -
per_gene Boolean Output only the most severe consequence per gene. The transcript selected is arbitrary if more than one has the same predicted consequence. Uses the same ranking system as pick. 0 -
pick Boolean Pick one line or block of consequence data per variant, including transcript-specific columns. Consequences are chosen according to the criteria described here, and the order the criteria are applied may be customised with pick_order. This is the best method to use if you are interested only in one consequence per variant. 0 -
pick_allele Boolean Like pick, but chooses one line or block of consequence data per variant allele. Will only differ in behaviour from pick when the input variant has multiple alternate alleles. 0 -
pick_allele_gene Boolean Like pick_allele, but chooses one line or block of consequence data per variant allele and gene combination. 0 -
pick_order String Comma-separated list with order of criteria (and the list of criteria) applied when choosing a block of annotation data with one of the following options: pick, pick_allele, per_gene, pick_allele_gene, flag_pick, flag_pick_allele, flag_pick_allele_gene. See this page for the default order. Valid criteria are: [ canonical appris tsl biotype ccds rank length mane_select mane_clinical ]. mane_select,mane_clinical,canonical,appris,tsl,biotype,ccds,rank,length -
protein Boolean Include Ensembl protein identifiers 0 -
refseq Boolean Use RefSeq transcript set to report consequences (human only) 0 -
shift_3prime Boolean Shift transcript-overlapping variants as far as possible in the 3' direction before providing consequences 0 -
shift_genomic Boolean Shift all variants as far as possible in the 3' direction before providing consequences 0 -
transcript_id String Filter results by Transcript ID Not Used -
transcript_version Boolean Add version numbers to Ensembl transcript identifiers 0 -
tsl Boolean Include transcript support level (TSL) annotation 0 -
uniprot Boolean Include best match accessions for translated protein products from three UniProt-related databases (SWISSPROT, TREMBL and UniParc) 0 -
variant_class Boolean Output the Sequence Ontology variant class for the input variant 0 -
vcf_string Boolean Include alleles in VCF format 0 -
xref_refseq Boolean Include aligned RefSeq mRNA identifiers for transcript. NB: theRefSeq and Ensembl transcripts aligned in this way MAY NOT, AND FREQUENTLY WILL NOT, match exactly in sequence, exon structure and protein product 0 -


application/json{ "hgvs_notations": array }{ "hgvs_notations" : ["AGT:c.803T>C", "9:g.22125503G>C" ] }

Example Requests


{ "hgvs_notations" : ["AGT:c.803T>C", "9:g.22125503G>C" ] }
use strict;
use warnings;

use HTTP::Tiny;

my $http = HTTP::Tiny->new();

my $server = '';
my $ext = '/vep/human/hgvs';
my $response = $http->request('POST', $server.$ext, {
  headers => { 
  	'Content-type' => 'application/json',
  	'Accept' => 'application/json'
  content => '{ "hgvs_notations" : ["AGT:c.803T>C", "9:g.22125503G>C" ] }'

die "Failed!\n" unless $response->{success};

use JSON;
use Data::Dumper;
if(length $response->{content}) {
  my $hash = decode_json($response->{content});
  local $Data::Dumper::Terse = 1;
  local $Data::Dumper::Indent = 1;
  print Dumper $hash;
  print "\n";

import requests, sys

server = ""
ext = "/vep/human/hgvs"
headers={ "Content-Type" : "application/json", "Accept" : "application/json"}
r =, headers=headers, data='{ "hgvs_notations" : ["AGT:c.803T>C", "9:g.22125503G>C" ] }')

if not r.ok:

decoded = r.json()
print repr(decoded)

import requests, sys

server = ""
ext = "/vep/human/hgvs"
headers={ "Content-Type" : "application/json", "Accept" : "application/json"}
r =, headers=headers, data='{ "hgvs_notations" : ["AGT:c.803T>C", "9:g.22125503G>C" ] }')

if not r.ok:

decoded = r.json()

require 'net/http'
require 'uri'

path = '/vep/human/hgvs'

url = URI.parse(server)
http =, url.port)

request =, {'Content-Type' => 'application/json', 'Accept' => 'application/json'})
request.body = '{ "hgvs_notations" : ["AGT:c.803T>C", "9:g.22125503G>C" ] }'

response = http.request(request)

if response.code != "200"
  puts "Invalid response: #{response.code}"
  puts response.body

require 'rubygems'
require 'json'
require 'yaml'

result = JSON.parse(response.body)
puts YAML::dump(result)


public class EnsemblRest {

  public static void main(String[] args) throws Exception {
    String server = "";
    String ext = "/vep/human/hgvs";
    URL url = new URL(server + ext);

    URLConnection connection = url.openConnection();
    HttpURLConnection httpConnection = (HttpURLConnection)connection;
    String postBody = "{ \"hgvs_notations\" : [\"AGT:c.803T>C\", \"9:g.22125503G>C\" ] }";
    httpConnection.setRequestProperty("Content-Type", "application/json");
    httpConnection.setRequestProperty("Accept", "application/json");
    httpConnection.setRequestProperty("Content-Length", Integer.toString(postBody.getBytes().length));

    DataOutputStream wr = new DataOutputStream(httpConnection.getOutputStream());

    InputStream response = connection.getInputStream();
    int responseCode = httpConnection.getResponseCode();

    if(responseCode != 200) {
      throw new RuntimeException("Response code was not 200. Detected response was "+responseCode);

    String output;
    Reader reader = null;
    try {
      reader = new BufferedReader(new InputStreamReader(response, "UTF-8"));
      StringBuilder builder = new StringBuilder();
      char[] buffer = new char[8192];
      int read;
      while ((read =, 0, buffer.length)) > 0) {
        builder.append(buffer, 0, read);
      output = builder.toString();
    finally {
        if (reader != null) try {
        } catch (IOException logOrIgnore) {



server <- ""
ext <- "/vep/human/hgvs"
r <- POST(paste(server, ext, sep = ""), content_type("application/json"), accept("application/json"), body = '{ "hgvs_notations" : ["AGT:c.803T>C", "9:g.22125503G>C" ] }')


# use this if you get a simple nested list back, otherwise inspect its structure
# head(data.frame(t(sapply(content(r),c))))

curl '' -H 'Content-type:application/json' \
-H 'Accept:application/json' -X POST -d '{ "hgvs_notations" : ["AGT:c.803T>C", "9:g.22125503G>C" ] }'

wget -q --header='Content-type:application/json' --header='Accept:application/json' \
--post-data='{ "hgvs_notations" : ["AGT:c.803T>C", "9:g.22125503G>C" ] }' \
''  -O -

Resource Information

Response formatsjson
Maximum POST size300