Ensembl REST API

Base URL

https://rest.ensembl.org

For the Ensembl Genomes (plants, fungi, bacteria, protists, metazoa):

https://rest.ensembl.org

(Same base; Ensembl Genomes was merged into the main REST API.)

For the GRCh37 (hg19) archive:

https://grch37.rest.ensembl.org

Authentication

No API key required. All endpoints are public.

Common Headers

All requests should include:

Content-Type: application/json

The API uses content negotiation. Append ?content-type=application/json to GET requests, or set the Accept header.

Key Endpoints

1. Gene lookup by symbol

GET /lookup/symbol/{species}/{symbol}?content-type=application/json

Parameter	Type	Description
`species`	string	Required. Species name (e.g., `homo_sapiens`, `mus_musculus`).
`symbol`	string	Required. Gene symbol (e.g., `TP53`, `BRCA1`).
`expand`	int	Set to `1` to include transcripts, translations, exons.

Example:

https://rest.ensembl.org/lookup/symbol/homo_sapiens/TP53?content-type=application/json
https://rest.ensembl.org/lookup/symbol/homo_sapiens/BRCA1?content-type=application/json;expand=1

Response:

json

{
  "id": "ENSG00000141510",
  "display_name": "TP53",
  "description": "tumor protein p53 [Source:HGNC Symbol;Acc:HGNC:11998]",
  "species": "homo_sapiens",
  "object_type": "Gene",
  "biotype": "protein_coding",
  "assembly_name": "GRCh38",
  "seq_region_name": "17",
  "start": 7661779,
  "end": 7687538,
  "strand": -1,
  "source": "ensembl_havana",
  "logic_name": "ensembl_havana_gene_homo_sapiens",
  "version": 16,
  "Transcript": [...]
}

2. Gene/feature lookup by Ensembl ID

GET /lookup/id/{id}?content-type=application/json

Parameter	Type	Description
`id`	string	Required. Ensembl stable ID (gene, transcript, protein, exon).
`expand`	int	Set to `1` to include child objects (transcripts for genes, etc.).
`db_type`	string	Database type: `core`, `otherfeatures`, `cdna`, `rnaseq`.

Example:

https://rest.ensembl.org/lookup/id/ENSG00000141510?content-type=application/json;expand=1
https://rest.ensembl.org/lookup/id/ENST00000269305?content-type=application/json
https://rest.ensembl.org/lookup/id/ENSP00000269305?content-type=application/json

3. Batch lookup (POST, up to 1000 IDs)

POST /lookup/id
Content-Type: application/json

{ "ids": ["ENSG00000141510", "ENSG00000012048", "ENSG00000157764"] }

Example response: Returns a map keyed by ID:

json

{
  "ENSG00000141510": {
    "id": "ENSG00000141510",
    "display_name": "TP53",
    ...
  },
  "ENSG00000012048": { ... }
}

4. Sequence retrieval

GET /sequence/id/{id}?content-type=application/json

Parameter	Type	Description
`id`	string	Ensembl stable ID (gene, transcript, or protein).
`type`	string	`genomic`, `cdna`, `cds`, `protein`. Default varies by object type.
`format`	string	`json` or `fasta`.
`expand_3prime`	int	Expand 3' end by N bases.
`expand_5prime`	int	Expand 5' end by N bases.
`mask`	string	`soft` (lowercase repeats) or `hard` (N-mask repeats).

Examples:

Protein sequence:

https://rest.ensembl.org/sequence/id/ENSP00000269305?content-type=application/json

CDS sequence:

https://rest.ensembl.org/sequence/id/ENST00000269305?type=cds&content-type=application/json

Genomic sequence with flanking:

https://rest.ensembl.org/sequence/id/ENSG00000141510?type=genomic&expand_5prime=1000&expand_3prime=500&content-type=application/json

FASTA format:

https://rest.ensembl.org/sequence/id/ENSP00000269305?content-type=text/x-fasta

Response (JSON):

json

{
  "id": "ENSP00000269305",
  "seq": "MEEPQSDPSVEPPLSQETFSDL...",
  "molecule": "protein",
  "desc": "chromosome:GRCh38:17:7661779:7687538:-1"
}

5. Sequence by region

GET /sequence/region/{species}/{region}?content-type=application/json

Region format: chromosome:start..end or chromosome:start..end:strand

Example:

https://rest.ensembl.org/sequence/region/homo_sapiens/17:7661779..7662000:1?content-type=application/json

6. Variant annotation (VEP -- Variant Effect Predictor)

By HGVS notation:

GET /vep/{species}/hgvs/{hgvs_notation}?content-type=application/json

Example:

https://rest.ensembl.org/vep/homo_sapiens/hgvs/ENST00000269305.9:c.817C>T?content-type=application/json
https://rest.ensembl.org/vep/homo_sapiens/hgvs/17:g.7674220G>A?content-type=application/json

By genomic region:

GET /vep/{species}/region/{region}/{allele}?content-type=application/json

Example:

https://rest.ensembl.org/vep/homo_sapiens/region/17:7674220-7674220:1/A?content-type=application/json

By rsID:

GET /vep/{species}/id/{rsid}?content-type=application/json

Example:

https://rest.ensembl.org/vep/homo_sapiens/id/rs699?content-type=application/json

VEP Response:

json

[
  {
    "input": "17:g.7674220G>A",
    "assembly_name": "GRCh38",
    "seq_region_name": "17",
    "start": 7674220,
    "end": 7674220,
    "strand": 1,
    "allele_string": "G/A",
    "most_severe_consequence": "missense_variant",
    "transcript_consequences": [
      {
        "gene_id": "ENSG00000141510",
        "gene_symbol": "TP53",
        "transcript_id": "ENST00000269305",
        "biotype": "protein_coding",
        "consequence_terms": ["missense_variant"],
        "impact": "MODERATE",
        "amino_acids": "R/H",
        "codons": "cGc/cAc",
        "protein_start": 248,
        "polyphen_prediction": "probably_damaging",
        "polyphen_score": 1.0,
        "sift_prediction": "deleterious",
        "sift_score": 0.0,
        "cadd_phred": 35.0
      }
    ],
    "colocated_variants": [
      {
        "id": "rs28934578",
        "frequencies": { ... },
        "clin_sig": ["pathogenic"]
      }
    ]
  }
]

Batch VEP (POST, up to 200 variants):

POST /vep/homo_sapiens/region
Content-Type: application/json

{ "variants": ["17 7674220 7674220 G/A 1", "7 140753336 140753336 A/T 1"] }

7. Variant (known variants by rsID)

GET /variation/{species}/{rsid}?content-type=application/json

Example:

https://rest.ensembl.org/variation/homo_sapiens/rs699?content-type=application/json

Response:

json

{
  "name": "rs699",
  "source": "Variants (including SNPs and indels) imported from dbSNP",
  "mappings": [
    {
      "seq_region_name": "1",
      "start": 230710048,
      "end": 230710048,
      "strand": 1,
      "allele_string": "A/G",
      "assembly_name": "GRCh38",
      "location": "1:230710048-230710048"
    }
  ],
  "MAF": 0.35,
  "minor_allele": "G",
  "clinical_significance": [],
  "synonyms": [],
  "ancestral_allele": "A"
}

8. Overlap / features in a region

GET /overlap/region/{species}/{region}?feature={type}&content-type=application/json

Parameter	Type	Description
`region`	string	Format: `chr:start-end`.
`feature`	string	One or more of: `gene`, `transcript`, `cds`, `exon`, `repeat`, `simple`, `misc`, `variation`, `somatic_variation`, `structural_variation`, `regulatory`, `motif`, `chipseq`, `constrained`. Can repeat parameter for multiple.

Example -- get all genes in a region:

https://rest.ensembl.org/overlap/region/homo_sapiens/17:7660000-7690000?feature=gene&content-type=application/json

Example -- get regulatory features:

https://rest.ensembl.org/overlap/region/homo_sapiens/17:7660000-7690000?feature=regulatory&content-type=application/json

9. Cross-references (Xrefs)

GET /xrefs/id/{id}?content-type=application/json

Example:

https://rest.ensembl.org/xrefs/id/ENSG00000141510?content-type=application/json

Returns links to external databases (HGNC, UniProt, NCBI Gene, RefSeq, etc.).

Response:

json

[
  {
    "primary_id": "11998",
    "display_id": "TP53",
    "dbname": "HGNC",
    "db_display_name": "HGNC Symbol"
  },
  {
    "primary_id": "P04637",
    "display_id": "P53_HUMAN",
    "dbname": "Uniprot/SWISSPROT"
  },
  {
    "primary_id": "7157",
    "display_id": "TP53",
    "dbname": "EntrezGene"
  }
]

Xrefs by symbol:

GET /xrefs/symbol/{species}/{symbol}?content-type=application/json

Example:

https://rest.ensembl.org/xrefs/symbol/homo_sapiens/TP53?content-type=application/json

10. Comparative genomics -- Homology

GET /homology/id/{id}?content-type=application/json

Parameter	Type	Description
`id`	string	Ensembl gene ID.
`type`	string	`orthologues`, `paralogues`, `projections`, `all`.
`target_species`	string	Filter to specific species (e.g., `mus_musculus`).
`target_taxon`	int	Filter to NCBI taxon ID.
`sequence`	string	`none`, `cdna`, `protein`. Include aligned sequences.

Example -- get mouse orthologs of human TP53:

https://rest.ensembl.org/homology/id/ENSG00000141510?type=orthologues&target_species=mus_musculus&content-type=application/json

Response:

json

{
  "data": [
    {
      "id": "ENSG00000141510",
      "homologies": [
        {
          "type": "ortholog_one2one",
          "target": {
            "id": "ENSMUSG00000059552",
            "species": "mus_musculus",
            "protein_id": "ENSMUSP00000073359",
            "perc_id": 77.8,
            "perc_pos": 86.0
          },
          "source": {
            "id": "ENSG00000141510",
            "species": "homo_sapiens",
            "protein_id": "ENSP00000269305"
          },
          "method_link_type": "ENSEMBL_ORTHOLOGUES",
          "dn_ds": 0.15
        }
      ]
    }
  ]
}

Homology by symbol:

GET /homology/symbol/{species}/{symbol}?content-type=application/json

Example:

https://rest.ensembl.org/homology/symbol/homo_sapiens/TP53?type=orthologues&target_species=mus_musculus&content-type=application/json

11. Regulatory features

GET /regulatory/species/{species}/id/{id}?content-type=application/json

Example:

https://rest.ensembl.org/regulatory/species/homo_sapiens/id/ENSR00000000163?content-type=application/json

12. Species information

GET /info/species?content-type=application/json

Returns all available species with assembly info.

13. Assembly information

GET /info/assembly/{species}?content-type=application/json

Example:

https://rest.ensembl.org/info/assembly/homo_sapiens?content-type=application/json

Returns chromosome names, lengths, assembly name (GRCh38), coordinate system, etc.

14. Phenotype by gene

GET /phenotype/gene/{species}/{gene}?content-type=application/json

Example:

https://rest.ensembl.org/phenotype/gene/homo_sapiens/TP53?content-type=application/json

15. LD (Linkage Disequilibrium)

GET /ld/{species}/pairwise/{rsid1}/{rsid2}?population_name={pop}&content-type=application/json

Example:

https://rest.ensembl.org/ld/homo_sapiens/pairwise/rs699/rs4762?population_name=1000GENOMES:phase_3:CEU&content-type=application/json

Common Species Names

Species	API Name
Human	`homo_sapiens`
Mouse	`mus_musculus`
Rat	`rattus_norvegicus`
Zebrafish	`danio_rerio`
Fruit fly	`drosophila_melanogaster`
Chicken	`gallus_gallus`
Dog	`canis_lupus_familiaris`
Pig	`sus_scrofa`

Rate Limits

15 requests per second for general users (no API key).
If you register for an API key (optional), higher limits may be available.
Requests exceeding the limit receive HTTP 429 with a Retry-After header.
Batch endpoints (POST) count as a single request -- use them to reduce call count.
Max 1000 IDs per batch POST for /lookup/id.
Max 200 variants per batch POST for VEP.
Rate limit headers are returned: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Error Format

json

{
  "error": "ID 'ENSG999' not found"
}

HTTP 400 for bad requests, 404 for not found, 429 for rate limiting, 503 for service unavailable.

Tips

Always append ?content-type=application/json to GET requests (or set the Accept header) -- the default is XML/HTML.
Use the GRCh37 base URL (grch37.rest.ensembl.org) if you need hg19 coordinates.
The /lookup/symbol endpoint is the fastest way to go from gene symbol to Ensembl ID.
For VEP, the HGVS endpoint is most convenient for single variants; the region POST endpoint is best for batch.
Combine /xrefs/id with gene IDs to cross-reference to UniProt, NCBI Gene, HGNC, and other databases.