GET overlap/region/:species/:region

Retrieves features (e.g. genes, transcripts, variants and more) that overlap a given region.

Parameters

Required

NameTypeDescriptionDefaultExample Values
feature Enum(band, gene, transcript, cds, exon, repeat, simple, misc, variation, somatic_variation, structural_variation, somatic_structural_variation, constrained, regulatory, motif, mane) The type of feature to retrieve. Multiple values are accepted. none -
region String Query region. A maximum of 5Mb is allowed to be requested at any one time - X:1..1000:1
X:1..1000:-1
X:1..1000
species String Species name/alias. - homo_sapiens

Optional

NameTypeDescriptionDefaultExample Values
biotype String Functional classification of the gene or transcript to fetch. Cannot be used in conjunction with logic_name when querying transcripts. - protein_coding
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
db_type String Specify the database type to retrieve features from if not using the core database. We automatically choose the correct type of DB for variation, comparative and regulation features. core core
otherfeatures
logic_name String Limit retrieval of genes, transcripts and exons by the name of analysis. - -
misc_set String Miscellaneous set which groups together feature entries. Consult the DB or returned data sets to discover what is available. - cloneset_30k
so_term String Sequence Ontology term to restrict the variants found. Its descendants are also included in the search. - SO:0001650
species_set String The species set name for retrieving constrained elements. mammals -
trim_downstream Boolean Do not return features which overlap the downstream end of the region. 0 -
trim_upstream Boolean Do not return features which overlap upstream end of the region. 0 -
variant_set String Short name of a set to restrict the variants found. (See list of short set names) - ClinVar

Example Requests

/overlap/region/human/7:140424943-140624564?feature=gene;feature=transcript;feature=cds;feature=exon;content-type=application/json


use strict;
use warnings;

use HTTP::Tiny;

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

my $server = 'https://grch37.rest.ensembl.org';
my $ext = '/overlap/region/human/7:140424943-140624564?feature=gene;feature=transcript;feature=cds;feature=exon';
my $response = $http->get($server.$ext, {
  headers => { 'Content-type' => 'application/json' }
});

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://grch37.rest.ensembl.org"
ext = "/overlap/region/human/7:140424943-140624564?feature=gene;feature=transcript;feature=cds;feature=exon"

r = requests.get(server+ext, headers={ "Content-Type" : "application/json"})

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

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

import requests, sys

server = "https://grch37.rest.ensembl.org"
ext = "/overlap/region/human/7:140424943-140624564?feature=gene;feature=transcript;feature=cds;feature=exon"

r = requests.get(server+ext, headers={ "Content-Type" : "application/json"})

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

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

require 'net/http'
require 'uri'

server='https://grch37.rest.ensembl.org'
path = '/overlap/region/human/7:140424943-140624564?feature=gene;feature=transcript;feature=cds;feature=exon'

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

request = Net::HTTP::Get.new(path, {'Content-Type' => 'application/json'})

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;


public class EnsemblRest {

  public static void main(String[] args) throws Exception {
    String server = "https://grch37.rest.ensembl.org";
    String ext = "/overlap/region/human/7:140424943-140624564?feature=gene;feature=transcript;feature=cds;feature=exon";
    URL url = new URL(server + ext);

    URLConnection connection = url.openConnection();
    HttpURLConnection httpConnection = (HttpURLConnection)connection;
    
    httpConnection.setRequestProperty("Content-Type", "application/json");
    

    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://grch37.rest.ensembl.org"
ext <- "/overlap/region/human/7:140424943-140624564?feature=gene;feature=transcript;feature=cds;feature=exon"

r <- GET(paste(server, ext, sep = ""), content_type("application/json"))

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://grch37.rest.ensembl.org/overlap/region/human/7:140424943-140624564?feature=gene;feature=transcript;feature=cds;feature=exon' -H 'Content-type:application/json'

wget -q --header='Content-type:application/json' 'https://grch37.rest.ensembl.org/overlap/region/human/7:140424943-140624564?feature=gene;feature=transcript;feature=cds;feature=exon'  -O -

/overlap/region/human/7:140424943-140624564?content-type=text/x-gff3;feature=gene;feature=transcript;feature=cds;feature=exon


use strict;
use warnings;

use HTTP::Tiny;

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

my $server = 'https://grch37.rest.ensembl.org';
my $ext = '/overlap/region/human/7:140424943-140624564?feature=gene;feature=transcript;feature=cds;feature=exon';
my $response = $http->get($server.$ext, {
  headers => { 'Content-type' => 'text/x-gff3' }
});

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


print "$response->{content}\n";

import requests, sys

server = "https://grch37.rest.ensembl.org"
ext = "/overlap/region/human/7:140424943-140624564?feature=gene;feature=transcript;feature=cds;feature=exon"

r = requests.get(server+ext, headers={ "Content-Type" : "text/x-gff3"})

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


print r.text

import requests, sys

server = "https://grch37.rest.ensembl.org"
ext = "/overlap/region/human/7:140424943-140624564?feature=gene;feature=transcript;feature=cds;feature=exon"

r = requests.get(server+ext, headers={ "Content-Type" : "text/x-gff3"})

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


print(r.text)

require 'net/http'
require 'uri'

server='https://grch37.rest.ensembl.org'
path = '/overlap/region/human/7:140424943-140624564?feature=gene;feature=transcript;feature=cds;feature=exon'

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

request = Net::HTTP::Get.new(path, {'Content-Type' => 'text/x-gff3'})

response = http.request(request)

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


puts response.body

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;


public class EnsemblRest {

  public static void main(String[] args) throws Exception {
    String server = "https://grch37.rest.ensembl.org";
    String ext = "/overlap/region/human/7:140424943-140624564?feature=gene;feature=transcript;feature=cds;feature=exon";
    URL url = new URL(server + ext);

    URLConnection connection = url.openConnection();
    HttpURLConnection httpConnection = (HttpURLConnection)connection;
    
    httpConnection.setRequestProperty("Content-Type", "text/x-gff3");
    

    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://grch37.rest.ensembl.org"
ext <- "/overlap/region/human/7:140424943-140624564?feature=gene;feature=transcript;feature=cds;feature=exon"

r <- GET(paste(server, ext, sep = ""), content_type("text/x-gff3"))

stop_for_status(r)


print(content(r))


curl 'https://grch37.rest.ensembl.org/overlap/region/human/7:140424943-140624564?feature=gene;feature=transcript;feature=cds;feature=exon' -H 'Content-type:text/x-gff3'

wget -q --header='Content-type:text/x-gff3' 'https://grch37.rest.ensembl.org/overlap/region/human/7:140424943-140624564?feature=gene;feature=transcript;feature=cds;feature=exon'  -O -

Resource Information

MethodsGET
Response formatsjson
xml
gff3
bed
jsonp
Slice length5e6