# Ensembl API
> The Ensembl genome database as an API, powered by the official Ensembl REST service from EMBL-EBI. Look up any gene by symbol or Ensembl stable id for its biotype, genomic location, strand, description and transcripts; resolve any feature (gene, transcript, exon) by stable id; pull external database cross-references; fetch sequence variants by rsID with their alleles, most-severe consequence, minor-allele frequency, clinical significance and genomic mappings; list the genes, transcripts, exons, variations or repeats overlapping any genomic region; retrieve genomic, cDNA, CDS or protein sequences by id; and read genome-assembly metadata including the karyotype and chromosome lengths. Across human, mouse and 300+ vertebrate species. Ideal for bioinformatics pipelines, genome browsers and variant-annotation tools, genetics research apps, clinical-genomics dashboards and life-science chatbots.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/ensembl-api/..."
```

## Pricing
- **Free** (Free) — 500 calls/Mo, 2 req/s
- **Starter** ($7/Mo) — 18,000 calls/Mo, 6 req/s
- **Pro** ($23/Mo) — 85,000 calls/Mo, 15 req/s
- **Mega** ($62/Mo) — 320,000 calls/Mo, 40 req/s

## Endpoints

### Genes

#### `GET /v1/gene` — Look up a gene by symbol

**Parameters:**
- `species` (query, optional, string) — Species (default human) Example: `human`
- `symbol` (query, required, string) — Gene symbol, e.g. BRCA2 Example: `BRCA2`
- `expand` (query, optional, string) — 1 = include transcripts

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/ensembl-api/v1/gene?species=human&symbol=BRCA2"
```

**Response:**
```json
{
    "data": {
        "gene": {
            "id": "ENSG00000139618",
            "end": 32400268,
            "start": 32315086,
            "source": "ensembl_havana",
            "strand": 1,
            "symbol": "BRCA2",
            "biotype": "protein_coding",
            "species": "human",
            "version": 19,
            "assembly": "GRCh38",
            "chromosome": "13",
            "description": "BRCA2 DNA repair associated [Source:HGNC Symbol;Acc:HGNC:1101]",
            "canonical_transcript": "ENST00000380152.8"
        }
    },
    "meta": {
        "timestamp": "2026-06-01T08:14:11.651Z",
        "request_id": "eeae2903-13a7-4203-b35f-a6d709ce42c8"
    },
    "status": "ok",
    "message": "Gene retrieved",
    "success": true
}
```

#### `GET /v1/lookup` — Any feature by Ensembl stable id

**Parameters:**
- `id` (query, required, string) — Ensembl stable id, e.g. ENSG00000139618 Example: `ENSG00000139618`
- `expand` (query, optional, string) — 1 = include transcripts

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/ensembl-api/v1/lookup?id=ENSG00000139618"
```

**Response:**
```json
{
    "data": {
        "feature": {
            "id": "ENSG00000139618",
            "end": 32400268,
            "type": "Gene",
            "start": 32315086,
            "parent": null,
            "strand": 1,
            "symbol": "BRCA2",
            "biotype": "protein_coding",
            "species": "homo_sapiens",
            "version": 19,
            "assembly": "GRCh38",
            "chromosome": "13",
            "description": "BRCA2 DNA repair associated [Source:HGNC Symbol;Acc:HGNC:1101]"
        }
    },
    "meta": {
        "timestamp": "2026-06-01T08:14:16.547Z",
        "request_id": "4f0cbe18-c928-44ba-9afd-24b88686ed57"
    },
    "status": "ok",
    "message": "Feature retrieved",
    "success": true
}
```

#### `GET /v1/xrefs` — External cross-references

**Parameters:**
- `species` (query, optional, string) — Species (default human) Example: `human`
- `symbol` (query, required, string) — Gene symbol Example: `BRCA2`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/ensembl-api/v1/xrefs?species=human&symbol=BRCA2"
```

**Response:**
```json
{
    "data": {
        "count": 2,
        "xrefs": [
            {
                "id": "ENSG00000139618",
                "type": "gene"
            },
            {
                "id": "LRG_293",
                "type": "gene"
            }
        ],
        "symbol": "BRCA2",
        "species": "human"
    },
    "meta": {
        "timestamp": "2026-06-01T08:14:16.721Z",
        "request_id": "88eb9c44-b25b-4586-93f5-395fbbf415b0"
    },
    "status": "ok",
    "message": "Cross-references retrieved",
    "success": true
}
```

### Variants

#### `GET /v1/region` — Features overlapping a region

**Parameters:**
- `species` (query, optional, string) — Species (default human) Example: `human`
- `region` (query, required, string) — chr:start-end (max 1 Mb) Example: `17:43044295-43125483`
- `feature` (query, optional, string) — gene|transcript|exon|variation|repeat|cds Example: `gene`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/ensembl-api/v1/region?species=human&region=17%3A43044295-43125483&feature=gene"
```

**Response:**
```json
{
    "data": {
        "count": 3,
        "region": "17:43044295-43125483",
        "feature": "gene",
        "species": "human",
        "features": [
            {
                "id": "ENSG00000240828",
                "end": 43079780,
                "name": "RPL21P4",
                "start": 43079302,
                "source": "havana",
                "strand": 1,
                "biotype": "processed_pseudogene",
                "consequence_type": null
            },
            {
                "id": "ENSG00000198496",
                "end": 43153671,
                "name": "NBR2",
                "start": 43125420,
                "source": "havana",
                "strand": 1,
                "biotype": "lncRNA",
                "consequence_type": null
            },
            {
                "id": "ENSG00000012048",
                "end": 43170245,
                "name": "BRCA1",
                "start": 43044292,
                "source": "ensembl_havana",
                "strand": -1,
                "biotype": "protein_coding",
                "consequence_type": null
            }
        ]
    },
    "meta": {
        "timestamp": "2026-06-01T08:14:16.860Z",
        "request_id": "08fe80db-8e8e-4b5c-a149-28b01422faa9"
    },
    "status": "ok",
    "message": "Region features retrieved",
    "success": true
}
```

#### `GET /v1/variant` — A sequence variant (rsID)

**Parameters:**
- `species` (query, optional, string) — Species (default human) Example: `human`
- `id` (query, required, string) — Variant id, e.g. rs699 Example: `rs699`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/ensembl-api/v1/variant?species=human&id=rs699"
```

**Response:**
```json
{
    "data": {
        "variant": {
            "name": "rs699",
            "source": "Variants (including SNPs and indels) imported from dbSNP",
            "evidence": [
                "Frequency",
                "1000Genomes",
                "Cited",
                "ESP",
                "Phenotype_or_Disease",
                "ExAC",
                "TOPMed",
                "gnomAD"
            ],
            "mappings": [
                {
                    "end": 230710048,
                    "start": 230710048,
                    "strand": 1,
                    "assembly": "GRCh38",
                    "location": "1:230710048-230710048",
                    "allele_string": "A/G",
                    "seq_region_name": "1"
                }
            ],
            "synonyms": [
                "106150.0001",
                "RCV000405686",
                "RCV000019691",
                "RCV000019693",
                "RCV000242838",
                "VCV000018068",
                "RCV000835695",
                "RCV002259306",
                "RCV000019692",
                "rs3182295",
                "rs17856353",
                "rs386606420",
                "rs4714",
                "rs61617185",
                "NM_001384479.1:c.776T>C",
                "NM_001382817.2:c.776T>C",
                "NM_001382817.1:c.803T>C",
                "NM_000029.3:c.803T>C",
                "NP_001371408.1:p.Met259Thr",
                "NM_000029.4:c.803T>C"
 
…(truncated, see openapi.json for full schema)
```

### Sequences

#### `GET /v1/sequence` — DNA / cDNA / CDS / protein sequence

**Parameters:**
- `id` (query, required, string) — Ensembl stable id Example: `ENSP00000369497`
- `type` (query, optional, string) — genomic|cds|cdna|protein Example: `protein`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/ensembl-api/v1/sequence?id=ENSP00000369497&type=protein"
```

**Response:**
```json
{
    "data": {
        "id": "ENSP00000369497",
        "type": "protein",
        "length": 3418,
        "molecule": "protein",
        "sequence": "MPIGSKERPTFFEIFKTRCNKADLGPISLNWFEELSSEAPPYNSEPAEESEHKNNNYEPNLFKTPQRKPSYNQLASTPIIFKEQGLTLPLYQSPVKELDKFKLDLGRNVPNSRHKSLRTVKTKMDQADDVSCPLLNSCLSESPVVLQCTHVTPQRDKSVVCGSLFHTPKFVKGRQTPKHISESLGAEVDPDMSWSSSLATPPTLSSTVLIVRNEEASETVFPHDTTANVKSYFSNHDESLKKNDRFIASVTDSENTNQREAASHGFGKTSGNSFKVNSCKDHIGKSMPNVLEDEVYETVVDTSEEDSFSLCFSKCRTKNLQKVRTSKTRKKIFHEANADECEKSKNQVKEKYSFVSEVEPNDTDPLDSNVANQKPFESGSDKISKEVVPSLACEWSQLTLSGLNGAQMEKIPLLHISSCDQNISEKDLLDTENKRKKDFLTSENSLPRISSLPKSEKPLNEETVVNKRDEEQHLESHTDCILAVKQAISGTSPVASSFQGIKKSIFRIRESPKETFNASFSGHMTDPNFKKETEASESGLEIHTVCSQKEDSLCPNLIDNGSWPATTTQNSVALKNAGLISTLKKKTNKFIYAIHDETSYKGKKIPKDQKSELINCSAQFEANAFEAPLTFANADSGLLHSSVKRSCSQNDSEEPTLSLTSSFGTILRKCSRNETCSNNTVISQDLDYKEAKCNKEKLQLFITPEADSLSCLQEGQCENDPKSKKVSDIKEEVLAAACHPVQHSKVEYSDTDFQSQKSLLYDHENASTLILTPTSKDVLSNLVMISRGKESYKMSDKLKGNNYESDVELTKNIPMEKNQDVCALNENYKNVELLPPEKYMRVASPSRKVQFNQNTNLRVIQKNQEETTSISKITVNPDSEELFSDNENNFVFQVANERNNLALGNTKELHETDLTCVNEPIFKNSTMVLYGDTGDKQATQVSIKKDLVYVLAEENKNSVKQHIKMTLGQDLKSDISLNIDKIPEKNNDYMNKWAGLLGPISNHSFGGSFRTASNKEIKLSEHNIKKSKMFFKDIEEQYPTSLACVEIVNTLALDNQKKLSKPQSINTVSAHLQSSVVVSDCKNSHITPQMLFSKQDFNSNHNLTPSQKAEITELSTILEESGSQFEFTQFRKPSYILQKSTFEVPENQMTILKTTSEECRDADLHVIMNAPSIGQVDSSKQFEGTVEIKRKFAGLLKNDCNKSASGYLTDENEVGFRGFYSAHGTKLNVSTEALQKAVKLFSDIENISEETSAEVHPISLSSSKCHDSVVSMFKIENHNDKTVSEKNNKCQLILQNNIEMTTGTFVEEITENYKRNTENEDNKYTAASRNSHNLEFDGSDSSKNDTVC
…(truncated, see openapi.json for full schema)
```

### Genome

#### `GET /v1/assembly` — Genome-assembly metadata

**Parameters:**
- `species` (query, optional, string) — Species (default human) Example: `human`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/ensembl-api/v1/assembly?species=human"
```

**Response:**
```json
{
    "data": {
        "species": "human",
        "assembly": {
            "date": "2013-12",
            "name": "GRCh38.p14",
            "accession": "GCA_000001405.29",
            "karyotype": [
                "1",
                "2",
                "3",
                "4",
                "5",
                "6",
                "7",
                "8",
                "9",
                "10",
                "11",
                "12",
                "13",
                "14",
                "15",
                "16",
                "17",
                "18",
                "19",
                "20",
                "21",
                "22",
                "X",
                "Y",
                "MT"
            ],
            "chromosomes": [
                {
                    "name": "Y",
                    "length": 57227415
                },
                {
                    "name": "20",
                    "length": 64444167
                },
                {
                    "name": "X",
                    "length": 156040895
                },
                {
                    "name": "13",
                    "length": 114364328
                },
                {
                    "name": "22",
                    "length": 50818468
                },
                {
                    "name": "10",
                    "length": 133797422
                },
                {
                    "name": "6",
   
…(truncated, see openapi.json for full schema)
```

### Meta

#### `GET /v1/meta` — Usage notes

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/ensembl-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "note": "The Ensembl genome database. /v1/gene?species=human&symbol=BRCA2 (add expand=1 for transcripts) = a gene's stable id, biotype, location & description; /v1/lookup?id=ENSG00000139618 = any feature by Ensembl stable id (gene/transcript/exon); /v1/xrefs?species=human&symbol=BRCA2 = external database cross-references; /v1/variant?species=human&id=rs699 = a sequence variant (alleles, consequence, minor-allele frequency, clinical significance, genomic mappings); /v1/region?species=human&region=17:43044295-43125483&feature=gene = features overlapping a genomic region (max 1 Mb; feature=gene|transcript|exon|variation|repeat|cds); /v1/sequence?id=ENSP00000369497&type=protein = the genomic|cds|cdna|protein sequence; /v1/assembly?species=human = genome-assembly metadata (assembly name, accession, karyotype, chromosomes). Species accept common names (human, mouse) or binomials (homo_sapiens). 300+ vertebrate species. Data courtesy of Ensembl / EMBL-EBI.",
        "source": "Ensembl REST API (rest.ensembl.org)",
        "endpoints": [
            "/v1/gene",
            "/v1/lookup",
            "/v1/xrefs",
            "/v1/variant",
            "/v1/region",
            "/v1/sequence",
            "/v1/assembly",
            "/v1/meta"
        ]
    },
    "meta": {
        "timestamp": "2026-06-01T08:14:25.482Z",
        "request_id": "abae661b-5220-48ca-b3d1-70d483bbfd1f"
    },
    "status": "ok",
    "message": "Meta retrieved",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/ensembl-api
OpenAPI spec: https://www.oanor.com/api/ensembl-api/openapi.json