ensembl-rest-api

Ensembl REST API Guide

Overview

Ensembl is a genome browser and annotation system maintained by EMBL-EBI and the Wellcome Sanger Institute, providing reference assemblies, gene annotations, variant data, and comparative genomics for over 300 vertebrate genomes. It is the genomic reference underpinning gget, PyEnsembl, and BioMart.

The REST API exposes Ensembl data via stateless HTTP. Researchers can look up genes by symbol or stable ID, retrieve genomic/cDNA/protein sequences, query variant annotations (rsIDs, clinical significance, consequences), access cross-references (HGNC, UniProt, RefSeq, OMIM), and obtain assembly metadata. Responses in JSON or XML.

Authentication

No authentication required. All endpoints are publicly accessible. Users needing higher throughput can register for an API token.

Core Endpoints

lookup/symbol: Gene Lookup by Symbol

Retrieve gene metadata: coordinates, biotype, canonical transcript.

• URL: GET https://rest.ensembl.org/lookup/symbol/{species}/{symbol}
• Parameters:

Parameter	Type	Required	Description
species	string	Yes	Species name (e.g., homo_sapiens)
symbol	string	Yes	Gene symbol (e.g., BRCA1, TP53)
expand	int	No	Set to 1 to include transcripts and translations
content-type	string	Yes	application/json or text/xml

• Example:

curl "https://rest.ensembl.org/lookup/symbol/homo_sapiens/BRCA1?content-type=application/json"

• Response (actual):

{
  "display_name": "BRCA1",
  "description": "BRCA1 DNA repair associated [Source:HGNC Symbol;Acc:HGNC:1100]",
  "object_type": "Gene", "species": "homo_sapiens",
  "assembly_name": "GRCh38", "biotype": "protein_coding",
  "seq_region_name": "17", "start": 43044292, "end": 43170245, "strand": -1,
  "id": "ENSG00000012048", "canonical_transcript": "ENST00000357654.9"
}