Ensembl REST API

  • Ensembl is one of the major resources for genomic information and genome annotation. It provides access to reference genomes, genes, transcripts, protein products, genetic variants, comparative genomics, regulatory elements, and functional annotations across many organisms. Researchers use Ensembl in genomics, transcriptomics, evolutionary biology, population genetics, functional annotation, and comparative genome analysis. The Ensembl REST API allows users to retrieve and analyse this information programmatically through standard web requests. It is particularly useful for automating data retrieval, integrating genomic information into bioinformatics pipelines, and developing reproducible computational analyses.
  • A REST API, or Representational State Transfer Application Programming Interface, enables software applications to communicate with a web service using HTTP requests. The Ensembl REST API provides access to Ensembl data through defined endpoints, each designed for a particular retrieval or analysis task. Researchers can access these services using Python, R, Perl, JavaScript, command-line tools, or any programming language capable of sending HTTP requests. Unlike manual browsing through the Ensembl website, programmatic access allows users to retrieve large collections of records, process genomic information automatically, and connect Ensembl data with other biological databases.
  • The principal Ensembl REST service is available at https://rest.ensembl.org/. It provides access to information from Ensembl databases through endpoints for gene and transcript lookup, sequence retrieval, genomic-region analysis, genetic variation, variant consequence prediction, comparative genomics, regulatory information, and cross-references. The API also provides information about available species, genome assemblies, database releases, and supported biological features. Ensembl maintains a separate REST service at https://grch37.rest.ensembl.org/ for accessing human data associated with the GRCh37 reference assembly. This distinction is important because genomic coordinates and annotations depend on the reference assembly being used.
  • The Ensembl REST API is organized into endpoints, which are specific web addresses associated with particular operations. An endpoint may retrieve a gene record, return a DNA sequence, identify variants in a genomic region, or predict the consequences of a genetic variant. Most endpoints use HTTP GET requests for retrieving information, while POST requests are available for submitting lists of identifiers, genomic regions, or variants. The requested response format is commonly specified through an HTTP Content-Type header, such as application/json or text/x-fasta, depending on the endpoint and required output.
  • One of the most useful endpoint groups is the lookup service. It retrieves information about Ensembl genes, transcripts, and protein identifiers. The lookup/id endpoint accepts a stable identifier and returns information about the corresponding biological record, including its species, genomic location, biotype, and relationships with other genomic features. For example, a gene identifier can be used to retrieve its chromosome, start and end positions, strand, and associated transcripts. The lookup/symbol endpoint allows users to search for a gene using a gene symbol and species name. This is useful when researchers know a gene name but do not know its Ensembl stable identifier.
  • A typical lookup request for a human gene symbol can be represented as: https://rest.ensembl.org/lookup/symbol/homo_sapiens/BRCA2?expand=1
  • The expand=1 parameter requests additional information about related transcripts and other features. The returned JSON record may include the gene’s stable identifier, display name, chromosome, genomic coordinates, strand, biotype, and transcript information. The exact fields depend on the endpoint and record. Researchers can use this information to identify a gene’s genomic position and obtain identifiers needed for further sequence retrieval or functional analysis.
  • Ensembl stable identifiers are particularly important when using the REST API. Genes, transcripts, and protein translations have separate identifiers, commonly beginning with prefixes such as ENSG, ENST, and ENSP in human records. A gene may have multiple transcripts, and different transcripts may encode different protein products. Stable identifiers allow researchers to distinguish these biological entities and retrieve the appropriate sequence or annotation. However, identifiers may have version suffixes, and changes in gene models or reference assemblies can affect the interpretation of records. Researchers should preserve the complete identifier and check its version and database release when reproducibility is important.
  • The sequence endpoint allows users to retrieve nucleotide and protein sequences using Ensembl stable identifiers. The sequence/id endpoint can return genomic, cDNA, coding DNA sequence (CDS), or protein translation sequences, depending on the identifier and requested sequence type. For example, a transcript identifier can be used to retrieve its cDNA sequence, while a translation identifier can retrieve the corresponding amino acid sequence. This is useful for sequence alignment, primer design, protein analysis, gene expression studies, and comparative genomics.
  • A sequence retrieval request can be constructed as follows: https://rest.ensembl.org/sequence/id/ENST00000357654?type=cdna
  • The type parameter specifies the sequence representation to retrieve. Common sequence types include genomic sequence, cDNA, CDS, and protein sequence, although the available options depend on the identifier and endpoint. The response can be returned in FASTA format by specifying the appropriate content type. Researchers should verify that the transcript or protein identifier belongs to the intended species and reference assembly before using the retrieved sequence in downstream analysis.
  • The API also provides a genomic-region sequence endpoint. The sequence/region endpoint retrieves DNA sequence from a specified chromosome or genomic region. A region is generally represented by a chromosome name, start coordinate, end coordinate, and optional strand. For example, a request may specify chromosome 7 from position 100000 to 101000 in Homo sapiens. This approach is useful when researchers need to retrieve a promoter region, gene-associated genomic interval, candidate regulatory region, or sequence surrounding a genetic variant. The reference assembly must be considered because the same coordinates may correspond to different sequences in different genome versions.
  • The overlap endpoint identifies genomic features that overlap a specified genomic region or Ensembl identifier. These features may include genes, transcripts, exons, coding sequences, variants, regulatory elements, and other annotations. For example, a researcher can query a chromosome interval to identify all genes and variants located within it. This is useful in genome annotation, regulatory genomics, variant analysis, and the investigation of candidate disease-associated regions. The feature type can be specified to restrict the results to particular categories, such as genes, transcripts, or variations. Ensembl documents a maximum region size of 5 Mb for the region overlap endpoint, so larger regions may need to be divided into smaller requests.
  • The overlap endpoint can also be used to investigate the genomic context of a genetic variant. Researchers may retrieve genes, transcripts, exons, or regulatory elements that overlap a variant position. Such information helps determine whether a variant is located within a coding region, intron, untranslated region, or regulatory feature. However, physical overlap does not by itself establish biological function or causality. Further analysis is needed to understand the potential effect of the variant.
  • The variation endpoints provide information about genetic variants recorded in Ensembl. The variation endpoint retrieves information about a variant using an identifier such as a dbSNP rsID. Depending on the species and available data, the returned record may include genomic location, alleles, allele frequencies, population information, genotype information, and phenotype associations. This information is useful in population genetics, disease research, evolutionary studies, and variant interpretation. Researchers should consider the reference assembly, population sample, and available evidence when interpreting variation data.
  • The Variant Effect Predictor (VEP) is one of the most important analytical services available through the Ensembl REST API. It predicts the potential consequences of genetic variants on genes, transcripts, and protein products. VEP can identify whether a variant is synonymous, missense, nonsense, intronic, splice-region, upstream, downstream, or associated with other molecular consequences. It can also provide transcript-specific annotations, affected protein positions, amino acid substitutions, and other information. These predictions help researchers prioritize variants for further investigation.
  • VEP can be accessed using variant identifiers, HGVS descriptions, or genomic coordinates. For example, a variant identified by an rsID can be submitted through the variant identifier endpoint. A genomic variant can also be represented using a chromosome position, reference allele, and alternate allele. The API returns annotations describing the predicted consequences across relevant transcripts and genes. The result may contain multiple annotations for a single variant because a genomic position can overlap several transcripts or genes. Researchers should therefore examine transcript-specific results rather than assuming that each variant has only one consequence.
  • The VEP service supports additional annotation options, including information about canonical transcripts, protein domains, conservation, known clinical annotations, and selected computational prediction resources. Some options require additional parameters or are restricted to particular species or datasets. For example, the canonical option identifies canonical transcript information, while hgvs requests HGVS descriptions based on Ensembl identifiers. Other supported options can provide information related to conservation, phenotype associations, and functional prediction tools. The exact options and their availability should be checked in the current VEP endpoint documentation.
  • A related service, Variant Recoder, converts variant descriptions between different representations. It can translate supported variant identifiers, HGVS descriptions, and genomic SPDI representations into alternative identifiers and notations. This is useful because the same genetic variant may be described differently across databases and analytical systems. Variant normalization and representation are essential for accurate comparison, annotation, and integration of variant data. Researchers should still verify the reference sequence and assembly associated with each representation.
  • The Ensembl REST API also supports comparative genomics. Comparative genomics investigates similarities and differences among the genomes of different organisms. Ensembl provides endpoints for retrieving homology information, gene trees, and genomic alignments. The homology endpoints can identify orthologues and paralogues associated with a gene. Orthologues are genes in different species that evolved from a common ancestral gene through speciation, whereas paralogues arise through gene duplication. These relationships are important for evolutionary studies and for identifying potential functional conservation between species.
  • Gene-tree endpoints provide evolutionary relationships among genes and their homologues. Researchers can use these data to investigate gene-family evolution, gene duplication, species divergence, and the distribution of gene families across organisms. Alignment endpoints retrieve comparative genomic alignments for specified regions and species. These resources support comparative genome analysis, identification of conserved regions, and investigation of evolutionary changes. As with other comparative resources, the interpretation of orthology and paralogy should consider the underlying gene models and evolutionary analysis methods.
  • The cross-reference endpoints connect Ensembl records with identifiers and records from external biological databases. The xrefs/id endpoint retrieves external references associated with an Ensembl identifier, while xrefs/symbol and xrefs/name allow users to search for linked records using symbols or external names. These connections may include identifiers from NCBI, UniProt, RefSeq, and other resources. Cross-references are particularly useful when integrating genomic information with protein sequences, functional annotations, publications, and other biological data. Mapping is not necessarily one-to-one, so researchers should examine the type of biological entity represented by each linked record.
  • The Ensembl REST API provides information endpoints that help users identify the data and species supported by the service. The info/species endpoint lists available species and associated information, while info/assembly provides information about genome assemblies and chromosome-level sequence regions. The info/data endpoint reports available Ensembl data releases, and info/rest reports the current REST API version. The info/biotypes endpoint provides information about gene and transcript biotypes, which can be used to distinguish protein-coding genes, long non-coding RNAs, pseudogenes, and other annotated feature types. These endpoints are useful when developing workflows that must adapt to different organisms or database releases.
  • The API also provides access to regulatory and phenotype-related information. Regulatory endpoints can retrieve regulatory features and binding matrices associated with transcription factor binding and gene regulation. Phenotype endpoints can retrieve phenotype annotations associated with genes, genomic regions, or ontology terms. Such information supports studies of gene regulation, disease-associated loci, and genotype–phenotype relationships. The availability and depth of these annotations vary among organisms and genomic regions.
  • Linkage disequilibrium (LD) endpoints allow researchers to investigate the statistical association between genetic variants in populations. LD describes the non-random association of alleles at different genomic positions. Ensembl provides endpoints for calculating LD between pairs of variants, between a variant and nearby variants, or among variants in a genomic region for supported populations. These services are useful in population genetics, association studies, and the interpretation of genome-wide association signals. LD patterns depend on population history, sample composition, allele frequencies, and the genomic region being studied, so the population used in an analysis must be selected carefully.
  • The Ensembl REST API can be accessed directly through a web browser for simple queries, but programming languages are more suitable for repeated and large-scale retrieval. Python is widely used for API-based bioinformatics because libraries such as requests make it straightforward to send HTTP requests and process JSON or FASTA responses. The following example retrieves information about a human gene using its symbol:

import requests

 

server = “https://rest.ensembl.org”

endpoint = “/lookup/symbol/homo_sapiens/BRCA2”

 

response = requests.get(

    server + endpoint,

    headers={“Content-Type”: “application/json”},

    params={“expand”: 1},

    timeout=30

)

 

response.raise_for_status()

gene_data = response.json()

 

print(“Gene ID:”, gene_data.get(“id”))

print(“Gene name:”, gene_data.get(“display_name”))

print(“Chromosome:”, gene_data.get(“seq_region_name”))

print(“Start:”, gene_data.get(“start”))

print(“End:”, gene_data.get(“end”))

print(“Strand:”, gene_data.get(“strand”))

  • This example sends a request to the lookup endpoint and retrieves a JSON response containing gene information. The expand parameter requests additional details about related features. The returned data can be used to identify the gene’s genomic location and retrieve its transcripts. Researchers should validate the returned species, identifier, and assembly before using the coordinates in an analysis.
  • A second example demonstrates how to retrieve a transcript sequence in FASTA format:

import requests

 

server = “https://rest.ensembl.org”

transcript_id = “ENST00000357654”

 

url = f”{server}/sequence/id/{transcript_id}”

 

response = requests.get(

    url,

    headers={“Content-Type”: “text/x-fasta”},

    params={“type”: “cdna”},

    timeout=30

)

 

response.raise_for_status()

 

print(response.text)

  • The returned FASTA sequence can be saved for subsequent analysis using sequence alignment, motif identification, primer design, or other computational methods. The transcript identifier in an example should always be checked against the current Ensembl release and the intended organism before being used in a real project.
  • The following example illustrates how to retrieve variant consequences through the VEP endpoint using a variant identifier:

import requests

 

server = “https://rest.ensembl.org”

species = “homo_sapiens”

variant_id = “rs56116432”

 

url = f”{server}/vep/{species}/id/{variant_id}”

 

response = requests.get(

    url,

    headers={“Content-Type”: “application/json”},

    params={“canonical”: 1, “protein”: 1},

    timeout=30

)

 

response.raise_for_status()

variant_data = response.json()

 

for variant in variant_data:

    print(“Input:”, variant.get(“input”))

    for consequence in variant.get(“transcript_consequences”, []):

        print(

            consequence.get(“gene_id”),

            consequence.get(“transcript_id”),

            consequence.get(“consequence_terms”)

        )

  • This example requests variant consequence information and includes canonical transcript and protein-related details where available. A variant may produce multiple transcript consequence records. The biological interpretation should consider the relevant transcript, genome assembly, allele representation, and supporting evidence. Computationally predicted consequences should not be treated as definitive proof of pathogenicity.
  • R can also be used to access the Ensembl REST API through packages such as httr2 and jsonlite. These packages allow researchers to construct HTTP requests, retrieve JSON responses, and convert the results into R objects for further analysis. The same approach can be used to retrieve gene annotations, transcript information, sequences, and variant consequences. R-based API access is particularly useful when Ensembl data must be integrated with statistical analysis, differential expression studies, genomic visualization, or other R-based bioinformatics workflows.
  • The API supports both single-record and batch operations. GET requests are convenient for retrieving information about one identifier or genomic region, while POST requests are available for submitting multiple identifiers, regions, or variants. Batch requests can reduce the overhead associated with sending many separate requests. However, researchers should follow the documented limits for each endpoint and divide large input collections into appropriate batches. The returned records should be checked to identify missing identifiers, incomplete results, and unexpected mappings.
  • Rate limits and responsible service use are important when working with the Ensembl REST API. The service applies request limits to protect its infrastructure and maintain availability for all users. Researchers should avoid sending large numbers of requests simultaneously, use batch endpoints where appropriate, and introduce delays or retry strategies when requests are temporarily limited. The API may return HTTP status codes indicating successful responses, missing records, invalid requests, or temporary server problems. Automated workflows should check response status codes, handle timeouts, and record failed requests rather than silently ignoring them. Current usage guidance should be consulted before running large-scale retrieval tasks.
  • The Ensembl REST API is a read-oriented service for accessing available Ensembl information; it is not a general-purpose interface for modifying the underlying Ensembl database. Its coverage is also limited to the data and endpoints exposed by the REST service. Some specialized analyses or complete database operations may require other resources, including Ensembl’s Perl API, downloadable database files, Ensembl BioMart, or dedicated command-line tools. The Ensembl website and its APIs may also differ in the information or interface available for particular data types.
  • BioMart provides an alternative way to retrieve large collections of Ensembl data using a graphical interface or programmatic queries. It is particularly useful for selecting specific attributes and filters to create gene, transcript, protein, and variation datasets. The REST API is often more suitable for targeted record retrieval and automated interactions with defined endpoints, whereas BioMart can be convenient for structured bulk extraction. Researchers may use both systems in the same workflow, depending on the required data and scale of analysis.
  • The Ensembl REST API supports integration with many other biological databases and computational tools. Gene identifiers can be mapped to external database references, protein sequences can be retrieved and analysed using sequence similarity tools, and variants can be annotated using VEP before further investigation in clinical or population databases. Comparative genomics information can be combined with gene expression, protein function, pathway, and structural data. These connections make the API valuable for multi-omics integration and the development of comprehensive bioinformatics pipelines.
  • Reproducibility is essential when using Ensembl data because genome assemblies, gene models, variant annotations, and database releases change over time. Researchers should record the species, stable identifiers, identifier versions, reference assembly, Ensembl release, API endpoint, query parameters, retrieval date, and output format. For variant analysis, the reference and alternate alleles, genomic coordinates, assembly, transcript selection, and VEP options should also be documented. The exact sequence or annotation records used in an analysis should be preserved when possible so that later database updates do not make the original results difficult to reproduce.
  • The Ensembl REST API is an important resource for automated access to genomic and comparative biological information. Its lookup, sequence, overlap, variation, VEP, homology, cross-reference, mapping, and information endpoints support a wide range of bioinformatics tasks. By combining these services with Python, R, and other computational tools, researchers can retrieve genome annotations, analyse genetic variants, compare genes across species, and integrate biological information into reproducible workflows. Its flexibility and broad biological coverage make it an essential tool for modern genomics, transcriptomics, evolutionary biology, and computational life sciences.
Author:

Leave a Reply

Your email address will not be published. Required fields are marked *