ensemblrestpy

Python client for the Ensembl REST API.

Complete access to all Ensembl REST API endpoints. Supports both procedural (standalone functions) and object-oriented (Ensembl class) interfaces. Works with GRCh38 and GRCh37 genome assemblies. Includes a CLI tool (ensembl) for terminal use.

---

Installation

Requirements: Python ≥ 3.12, requests

From PyPI

pip install ensemblrestpy

From source

git clone https://github.com/liu-sun/ensemblrestpy.git
cd ensemblrestpy
pip install -e .

After installation, the ensembl command is available in your terminal.

---

Quick Start

Module-level functions (GRCh38)

>>> from ensemblrestpy import ping, archive_id, vep_hgvs

>>> ping()
{"ping": 1}

>>> archive_id("ENSG00000157764")
{"id": "ENSG00000157764", "version": 15, "type": "Gene", ...}

>>> vep_hgvs("NM_000410.4:c.845G>A", "human")
[{"input": "NM_000410.4:c.845G>A", "transcript_consequences": [...], ...}]

Ensembl class (session reuse for multiple calls)

>>> from ensemblrestpy import Ensembl
>>> e = Ensembl()
>>> e.ping()
{"ping": 1}
>>> e.archive_id("ENSG00000157764")
{"id": "ENSG00000157764", "version": 15, ...}

Command-line interface

$ ensembl ping
{"ping": 1}

$ ensembl archive_id ENSG00000157764
{
  "id": "ENSG00000157764",
  "version": 15,
  "type": "Gene"
}

$ ensembl vep_hgvs "NM_000410.4:c.845G>A" human
$ ensembl grch37 ping
$ ensembl --format xml ping

GRCh37

>>> from ensemblrestpy.grch37 import ping, archive_id, vep_hgvs
>>> ping()
{"ping": 1}
>>> archive_id("ENSG00000157764")
{"id": "ENSG00000157764", "version": 8, "assembly": "GRCh37", ...}

$ ensembl grch37 archive_id ENSG00000157764

---

Key Features

Response formats

Ten formats supported via response_format (default json):

json | xml | fasta | text | yaml | nh | phyloxml | orthoxml | gff3 | bed | seqxml

>>> from ensemblrestpy import sequence_id
>>> seq = sequence_id("ENSG00000157764", response_format="fasta")

CLI: ensembl --format fasta sequence_id ENSG00000157764

Singledispatch: single ID vs bulk list

Endpoints that accept one or many IDs use Python's singledispatch:

>>> variation_id("rs1800562", "human")                    # GET: single
>>> variation_id(["rs1800562", "rs1799945"], "human")      # POST: bulk

Automatic rate limiting

requests.Session with retry/backoff. HTTP 429 responses are retried automatically.

Convenience partials (species="human" pre-filled)

>>> from ensemblrestpy import vep_hgvs_human, variation_id_human
>>> vep_hgvs_human("NM_000410.4:c.845G>A")
>>> variation_id_human("rs1800562")

---

Endpoint Reference

Archive

archive_id

Comparative Genomics

cafe_tree cafe_tree_member_symbol cafe_tree_species_member_id genetree genetree_member_symbol genetree_species_member_id genomic_alignment_region homology_species_gene_id homology_symbol

Cross References

xref_external xref_id xref_name

Info & Metadata

analysis assembly_info assembly_stats biotypes biotypes_groups biotypes_name compara_methods compara_species_sets comparas data eg_version external_dbs info_divisions info_genome info_genomes_accession info_genomes_assembly info_genomes_division info_genomes_taxonomy ping rest software species variation_consequence_types variation_populations variation_population_name

Lookup

lookup_id lookup_symbol

Mapping

assembly_cdna assembly_cds assembly_map assembly_translation

Ontology & Taxonomy

ontology_ancestors ontology_ancestors_chart ontology_descendants ontology_id ontology_name taxonomy_classification taxonomy_id taxonomy_name

Overlap

overlap_id overlap_region overlap_translation

Phenotype

phenotype_accession phenotype_gene phenotype_region phenotype_term

Regulation

get_binding_matrix

Sequences

sequence_id sequence_region sequence_region_post

Transcript Haplotypes

transcript_haplotypes_get

Variation

variation variation_id variation_pmcid variation_pmid variation_post ld_id_get ld_pairwise_get ld_region_get

VEP (Variant Effect Predictor)

vep_hgvs vep_id vep_region variant_recoder

GA4GH

beacon_get beacon_query_get beacon_query_post features_id features_post gacallSet gacallset_id gadataset gadataset_id gafeatureset gafeatureset_id gavariant_id gavariantannotations gavariants gavariantset gavariantset_id references references_id referenceSets referenceSets_id VariantAnnotationSet VariantAnnotationSet_id

Every endpoint is available as both a module-level function and an Ensembl class method. All endpoints are available for both GRCh38 and GRCh37.

---

License

MIT — see LICENSE.

Links

• PyPI: pypi.org/project/ensemblrestpy
• GitHub: github.com/liu-sun/ensemblrestpy
• Issues: github.com/liu-sun/ensemblrestpy/issues
• Ensembl REST API: rest.ensembl.org