Service logo

POST ga4gh/beacon/query

Return the Beacon response for allele information

Parameters

Required

NameTypeDescriptionDefaultExample Values
alternateBases String The bases that appear instead of the reference bases. Accepted values: see the ALT field in VCF 4.2 specification (http://samtools.github.io/hts-specs/VCFv4.2.pdf) Note: either alternateBases or variantType is required. - C
assemblyId String Assembly identifier (GRC notation, e.g. GRCh38). - GRCh38
end Int Precise end position, allele locus (0-based). Accepted values: non-negative integers smaller than reference length. Note: only required when using variantType to query precise structural variants. - __VAR(GA4GH_beacon_end)__
endMax Int Maximum end coordinate, allele locus (0-based). Accepted values: non-negative integers smaller than reference length. Note: only required when using variantType to query imprecise structural variants. - __VAR(GA4GH_beacon_endmax)__
endMin Int Minimum end coordinate, allele locus (0-based). Accepted values: non-negative integers smaller than reference length. Note: only required when using variantType to query imprecise structural variants. - __VAR(GA4GH_beacon_endmin)__
referenceBases String Reference bases for this variant (starting from start). Accepted values: see the REF field in VCF 4.2 specification (http://samtools.github.io/hts-specs/VCFv4.2.pdf). - G
referenceName String Reference name (chromosome). Accepted values: 1-22, X, Y, MT. - 9
start Int Precise start position, allele locus (0-based). Accepted values: non-negative integers smaller than reference length. Note: Do not use when querying for imprecise structural variants, use startMin - 22125503
startMax Int Maximum start coordinate, allele locus (0-based). Accepted values: non-negative integers smaller than reference length. Note: only required when using variantType to query imprecise structural variants. - __VAR(GA4GH_beacon_startmax)__
startMin Int Minimum start coordinate, allele locus (0-based). Accepted values: non-negative integers smaller than reference length. Note: only required when using variantType to query imprecise structural variants. - __VAR(GA4GH_beacon_startmin)__
variantType String Used to denote structural variants. Accepted values: DUP,DEL,INS,INV,CNV,DUP:TANDEM, see the ALT field in VCF 4.2 specification (http://samtools.github.io/hts-specs/VCFv4.2.pdf) Note: either alternateBases or variantType is required. - __VAR(GA4GH_beacon_variantType)__

Optional

NameTypeDescriptionDefaultExample Values
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
datasetIds array of strings Identifiers of datasets. Identifiers have to be chosen from 'Short name' column in the Variant sets list (http://www.ensembl.org/info/genome/variation/species/sets.html) - -
includeDatasetResponses String Indicator of whether responses for individual datasets should be included. Accepted values: ALL, HIT, MISS, NONE. NONE -

Message

Content-typeFormatExample
application/json{ "referenceName": string, "start": integer, "referenceBases": string, "alternateBases": string, "assemblyId": string}{ "referenceName": "9", "start" : 22125503, "referenceBases": "G", "alternateBases": "C","assemblyId" : "GRCh38" }

Example Requests

/ga4gh/beacon/query


{ "referenceName": "9", "start" : 22125503, "referenceBases": "G", "alternateBases": "C","assemblyId" : "GRCh38" }
        
use strict;
use warnings;

use HTTP::Tiny;

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

my $server = 'https://jan2020.rest.ensembl.org';
my $ext = '/ga4gh/beacon/query';
my $response = $http->request('POST', $server.$ext, {
  headers => { 
  	'Content-type' => 'application/json',
  	'Accept' => 'application/json'
  },
  content => '{ "referenceName": "9", "start" : 22125503, "referenceBases": "G", "alternateBases": "C","assemblyId" : "GRCh38" }'
});

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 = "https://jan2020.rest.ensembl.org"
ext = "/ga4gh/beacon/query"
headers={ "Content-Type" : "application/json", "Accept" : "application/json"}
r = requests.post(server+ext, headers=headers, data='{ "referenceName": "9", "start" : 22125503, "referenceBases": "G", "alternateBases": "C","assemblyId" : "GRCh38" }')

if not r.ok:
  r.raise_for_status()
  sys.exit()

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


import requests, sys

server = "https://jan2020.rest.ensembl.org"
ext = "/ga4gh/beacon/query"
headers={ "Content-Type" : "application/json", "Accept" : "application/json"}
r = requests.post(server+ext, headers=headers, data='{ "referenceName": "9", "start" : 22125503, "referenceBases": "G", "alternateBases": "C","assemblyId" : "GRCh38" }')

if not r.ok:
  r.raise_for_status()
  sys.exit()

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


require 'net/http'
require 'uri'

server='https://jan2020.rest.ensembl.org'
path = '/ga4gh/beacon/query'

url = URI.parse(server)
http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(path, {'Content-Type' => 'application/json', 'Accept' => 'application/json'})
request.body = '{ "referenceName": "9", "start" : 22125503, "referenceBases": "G", "alternateBases": "C","assemblyId" : "GRCh38" }'

response = http.request(request)

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


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

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


import java.net.URL;
import java.net.URLConnection;
import java.net.HttpURLConnection;
import java.io.BufferedReader;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.io.IOException;
import java.io.Reader;
import java.io.DataOutputStream;


public class EnsemblRest {

  public static void main(String[] args) throws Exception {
    String server = "https://jan2020.rest.ensembl.org";
    String ext = "/ga4gh/beacon/query";
    URL url = new URL(server + ext);

    URLConnection connection = url.openConnection();
    HttpURLConnection httpConnection = (HttpURLConnection)connection;
    
    String postBody = "{ \"referenceName\": \"9\", \"start\" : 22125503, \"referenceBases\": \"G\", \"alternateBases\": \"C\",\"assemblyId\" : \"GRCh38\" }";
    httpConnection.setRequestMethod("POST");
    httpConnection.setRequestProperty("Content-Type", "application/json");
    httpConnection.setRequestProperty("Accept", "application/json");
    httpConnection.setRequestProperty("Content-Length", Integer.toString(postBody.getBytes().length));
    httpConnection.setUseCaches(false);
    httpConnection.setDoInput(true);
    httpConnection.setDoOutput(true);

    DataOutputStream wr = new DataOutputStream(httpConnection.getOutputStream());
    wr.writeBytes(postBody);
    wr.flush();
    wr.close();
    

    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 = reader.read(buffer, 0, buffer.length)) > 0) {
        builder.append(buffer, 0, read);
      }
      output = builder.toString();
    } 
    finally {
        if (reader != null) try {
          reader.close(); 
        } catch (IOException logOrIgnore) {
          logOrIgnore.printStackTrace();
        }
    }

    System.out.println(output);
  }
}


library(httr)
library(jsonlite)
library(xml2)

server <- "https://jan2020.rest.ensembl.org"
ext <- "/ga4gh/beacon/query"
r <- POST(paste(server, ext, sep = ""), content_type("application/json"), accept("application/json"), body = '{ "referenceName": "9", "start" : 22125503, "referenceBases": "G", "alternateBases": "C","assemblyId" : "GRCh38" }')

stop_for_status(r)

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


curl 'https://jan2020.rest.ensembl.org/ga4gh/beacon/query' -H 'Content-type:application/json' \
-H 'Accept:application/json' -X POST -d '{ "referenceName": "9", "start" : 22125503, "referenceBases": "G", "alternateBases": "C","assemblyId" : "GRCh38" }'


wget -q --header='Content-type:application/json' --header='Accept:application/json' \
--post-data='{ "referenceName": "9", "start" : 22125503, "referenceBases": "G", "alternateBases": "C","assemblyId" : "GRCh38" }' \
'https://jan2020.rest.ensembl.org/ga4gh/beacon/query'  -O -

/ga4gh/beacon/query


{ "referenceName": "9", "start" : 22125503, "referenceBases": "G", "alternateBases": "C","assemblyId" : "GRCh38","includeDatasetResponses": "NONE"  }
        
use strict;
use warnings;

use HTTP::Tiny;

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

my $server = 'https://jan2020.rest.ensembl.org';
my $ext = '/ga4gh/beacon/query';
my $response = $http->request('POST', $server.$ext, {
  headers => { 
  	'Content-type' => 'application/json',
  	'Accept' => 'application/json'
  },
  content => '{ "referenceName": "9", "start" : 22125503, "referenceBases": "G", "alternateBases": "C","assemblyId" : "GRCh38","includeDatasetResponses": "NONE"  }'
});

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 = "https://jan2020.rest.ensembl.org"
ext = "/ga4gh/beacon/query"
headers={ "Content-Type" : "application/json", "Accept" : "application/json"}
r = requests.post(server+ext, headers=headers, data='{ "referenceName": "9", "start" : 22125503, "referenceBases": "G", "alternateBases": "C","assemblyId" : "GRCh38","includeDatasetResponses": "NONE"  }')

if not r.ok:
  r.raise_for_status()
  sys.exit()

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


import requests, sys

server = "https://jan2020.rest.ensembl.org"
ext = "/ga4gh/beacon/query"
headers={ "Content-Type" : "application/json", "Accept" : "application/json"}
r = requests.post(server+ext, headers=headers, data='{ "referenceName": "9", "start" : 22125503, "referenceBases": "G", "alternateBases": "C","assemblyId" : "GRCh38","includeDatasetResponses": "NONE"  }')

if not r.ok:
  r.raise_for_status()
  sys.exit()

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


require 'net/http'
require 'uri'

server='https://jan2020.rest.ensembl.org'
path = '/ga4gh/beacon/query'

url = URI.parse(server)
http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(path, {'Content-Type' => 'application/json', 'Accept' => 'application/json'})
request.body = '{ "referenceName": "9", "start" : 22125503, "referenceBases": "G", "alternateBases": "C","assemblyId" : "GRCh38","includeDatasetResponses": "NONE"  }'

response = http.request(request)

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


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

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


import java.net.URL;
import java.net.URLConnection;
import java.net.HttpURLConnection;
import java.io.BufferedReader;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.io.IOException;
import java.io.Reader;
import java.io.DataOutputStream;


public class EnsemblRest {

  public static void main(String[] args) throws Exception {
    String server = "https://jan2020.rest.ensembl.org";
    String ext = "/ga4gh/beacon/query";
    URL url = new URL(server + ext);

    URLConnection connection = url.openConnection();
    HttpURLConnection httpConnection = (HttpURLConnection)connection;
    
    String postBody = "{ \"referenceName\": \"9\", \"start\" : 22125503, \"referenceBases\": \"G\", \"alternateBases\": \"C\",\"assemblyId\" : \"GRCh38\",\"includeDatasetResponses\": \"NONE\"  }";
    httpConnection.setRequestMethod("POST");
    httpConnection.setRequestProperty("Content-Type", "application/json");
    httpConnection.setRequestProperty("Accept", "application/json");
    httpConnection.setRequestProperty("Content-Length", Integer.toString(postBody.getBytes().length));
    httpConnection.setUseCaches(false);
    httpConnection.setDoInput(true);
    httpConnection.setDoOutput(true);

    DataOutputStream wr = new DataOutputStream(httpConnection.getOutputStream());
    wr.writeBytes(postBody);
    wr.flush();
    wr.close();
    

    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 = reader.read(buffer, 0, buffer.length)) > 0) {
        builder.append(buffer, 0, read);
      }
      output = builder.toString();
    } 
    finally {
        if (reader != null) try {
          reader.close(); 
        } catch (IOException logOrIgnore) {
          logOrIgnore.printStackTrace();
        }
    }

    System.out.println(output);
  }
}


library(httr)
library(jsonlite)
library(xml2)

server <- "https://jan2020.rest.ensembl.org"
ext <- "/ga4gh/beacon/query"
r <- POST(paste(server, ext, sep = ""), content_type("application/json"), accept("application/json"), body = '{ "referenceName": "9", "start" : 22125503, "referenceBases": "G", "alternateBases": "C","assemblyId" : "GRCh38","includeDatasetResponses": "NONE"  }')

stop_for_status(r)

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


curl 'https://jan2020.rest.ensembl.org/ga4gh/beacon/query' -H 'Content-type:application/json' \
-H 'Accept:application/json' -X POST -d '{ "referenceName": "9", "start" : 22125503, "referenceBases": "G", "alternateBases": "C","assemblyId" : "GRCh38","includeDatasetResponses": "NONE"  }'


wget -q --header='Content-type:application/json' --header='Accept:application/json' \
--post-data='{ "referenceName": "9", "start" : 22125503, "referenceBases": "G", "alternateBases": "C","assemblyId" : "GRCh38","includeDatasetResponses": "NONE"  }' \
'https://jan2020.rest.ensembl.org/ga4gh/beacon/query'  -O -

Resource Information

MethodsPOST
Response formatsjson
jsonp