Getting Started with ensembl-rest-client

version: 0.2.0

ensembl-rest-client provides Pythonic access to the Ensembl REST API. It implements most current endpoints at the Ensembl REST base URL (https://rest.ensembl.org) and was last refreshed against Ensembl REST ~15.12–16.0.

Python support: 3.9–3.13 (requires-python = ">=3.9,<3.14").

Every public get_* / post_* method has a core offline test (mocked path construction). Live probes that hit Ensembl REST are opt-in only (see below).

If you find a wrapper, parameter, or docs page that looks stale or out of date relative to the live Ensembl REST service, first check endpoint coverage against the official catalog (from a clone of this repo):

python resources/bin/check_endpoint_coverage.py
python resources/bin/check_endpoint_coverage.py --live

That reports paths Ensembl lists that we lack, and wrappers we ship that are no longer on the catalog. Details: Sphinx User guide → Endpoint coverage.

If coverage looks fine but behaviour is still wrong, please contact us (or open an issue on GitLab) and we will refresh the client.

Breaking changes in 0.2.x

Hard removals and signature changes (no compatibility shims):

• Comparative genomics member/homology by-id methods require species as the first argument (path form used by Ensembl REST ≥15.8)
• Removed: eQTL wrappers (Ensembl REST 15.0) — use the EMBL-EBI eQTL Catalogue instead
• Removed: gene family methods (REST 15.3)
• Removed: regulation microarray / epigenome / regulatory-id wrappers (REST 15.9); binding-matrix remains

Full notes are in the Changelog (Project admin in these docs) or CHANGELOG.md on GitLab.

Other Ensembl REST clients exist; depending on your needs you may prefer:

• pyEnsemblRest on PyPI
• ensembl-rest on PyPI

Installation instructions

You can install using pip or conda.

Installation using pip

pip install ensembl-rest-client

Installation using conda

I maintain a conda package in my personal conda channel. To install this please run:

conda install -c cfin -c conda-forge ensembl-rest-client

Basic usage

from ensembl_rest_client.client import Rest

# Rate-limited client (default max 15 requests/sec); optional on-disk cache
rc = Rest(cache=False)

gene = rc.get_lookup_id("ENSG00000139618")
print(gene["display_name"], gene["biotype"])

The Rest class merges every endpoint domain (lookup, VEP, sequence, …) with shared HTTP behaviour (retries, wait times, optional cache). Domain modules can also be composed as mix-ins; see the User guide in these docs.

Helper workflows (nearest genes, chromosome window traversal, LD from coordinates) live in ensembl_rest_client.utils.

Examples in this documentation (sidebar Programmer reference):

• Narrative notebooks (with printed output): lookup, sequence, variation, VEP, overlap, xrefs, homology, LD
• API call examples — minimal call for every public method with truncated live sample output (regenerate with python resources/bin/gen_api_examples.py --with-outputs)

Run tests

If you have cloned the repository, install an editable checkout first so tests use this tree rather than an older wheel from site-packages:

pip install -e ".[dev]"

# Default: offline suite (no network). Includes full API surface path checks
# plus focused unit suites (VEP kwargs, regulation, removals, …).
pytest ./tests

# Offline API surface only (every get_/post_ method, mocked rest_query)
pytest ./tests/test_api_offline.py -q

# Live probes (must ask for them explicitly):
#   1. set ENSEMBL_LIVE=1
#   2. select the live marker
ENSEMBL_LIVE=1 pytest ./tests -m live

# Live full-surface smokes only (one core call per non-stub method)
ENSEMBL_LIVE=1 pytest ./tests/test_api_live.py -m live

• Offline: mocks rest_query; asserts HTTP method + endpoint path for every public Rest method (tests/api_call_specs.py)
• Live: hits the Ensembl REST service (https://rest.ensembl.org); soft-checks dict/list payloads
• Gate: both ENSEMBL_LIVE=1 and @pytest.mark.live / -m live
• Markers and pythonpath are registered in tests/pytest.ini
• Stub exception: post_lookup_symbol raises NotImplementedError (covered offline only)

If any fail please contact us (see the contribution page for contact info).