ensemblrestpy 15.11

Python client for Ensembl REST API

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