Ensembl Gene Scraper - Gene IDs, Biotype, Location & Descriptions

Turn a plain list of gene symbols (BRCA2, TP53, EGFR) or Ensembl gene IDs (ENSG00000139618) into a clean, structured dataset: stable Ensembl ID, gene symbol, description, biotype, chromosome, start/end coordinates, strand, gene length, genome assembly and a direct link to the Ensembl gene page.

No API key. No login. No cookies. Works on Apify's shared datacenter proxies out of the box, and covers every species in Ensembl - human, mouse, rat, zebrafish, fruit fly, yeast, plants and more.

---

What this actor does

The Ensembl REST API is the reference source for genome annotation, but it returns raw JSON one gene at a time and is easy to get wrong (species-scoped symbol lookups, 400s instead of 404s, a ~15 requests/second rate limit). This actor wraps it into a batch-friendly scraper:

• Batch lookups - up to 50 genes per request via Ensembl's POST endpoints, with automatic per-gene fallback if a batch fails.
• Two input modes - start from gene symbols + a species, or from stable Ensembl gene IDs.
• Any species - homo_sapiens, mus_musculus, danio_rerio, drosophila_melanogaster, saccharomyces_cerevisiae, and everything else Ensembl annotates.
• Rate-limit aware - paced requests with retries and backoff so long lists finish instead of getting throttled.
• Clean, flat output - one row per gene, ready for CSV, Excel, JSON, or a direct API pull into your pipeline.

Use cases

• Genomics - annotate a gene list from a screen, a panel, or a variant caller with coordinates, biotype and assembly.
• Bioinformatics - map gene symbols to stable Ensembl IDs before a join with expression matrices, GTF files, or another database.
• Gene research - pull descriptions, biotypes and locations for a target list without clicking through the Ensembl website.
• Datasets - build reusable reference tables of genes per species for dashboards, teaching material, or internal tooling.

Input

Field	Type	Default	Description
mode	select	symbols	symbols = look up gene symbols within a species. ids = look up Ensembl gene IDs directly.
symbols	array	["BRCA2","TP53"]	Gene symbols to resolve. Used in symbols mode.
species	string	homo_sapiens	Ensembl species name in snake_case. Used in symbols mode.
geneIds	array	-	Stable Ensembl gene IDs, e.g. ENSG00000139618. Used in ids mode.
maxItems	integer	100	Maximum number of gene records to push (max 1000).

Example - symbols mode

{
  "mode": "symbols",
  "symbols": ["BRCA2", "TP53", "EGFR", "MYC"],
  "species": "homo_sapiens",
  "maxItems": 100
}

Example - IDs mode

{
  "mode": "ids",
  "geneIds": ["ENSG00000139618", "ENSG00000141510", "ENSMUSG00000041147"],
  "maxItems": 100
}

Output

One dataset item per gene:

{
  "ensembl_id": "ENSG00000139618",
  "symbol": "BRCA2",
  "description": "BRCA2 DNA repair associated [Source:HGNC Symbol;Acc:HGNC:1101]",
  "biotype": "protein_coding",
  "species": "homo_sapiens",
  "chromosome": "13",
  "start": 32315086,
  "end": 32400268,
  "strand": 1,
  "length": 85182,
  "assembly": "GRCh38",
  "object_type": "Gene",
  "version": 19,
  "source_db": "ensembl_havana",
  "url": "https://www.ensembl.org/homo_sapiens/Gene/Summary?g=ENSG00000139618",
  "source": "ensembl",
  "scraped_at": "2026-07-28T11:36:45.521715+00:00"
}

Every field is nullable - upstream annotation is uneven across species, and the actor never invents data.

Pricing

Roughly $0.5 per 1,000 genes on the Apify platform, depending on your plan's compute-unit rate. The actor runs on 512 MB and batches 50 genes per request, so a 1,000-gene list finishes in well under a minute.

Tips

• Symbol lookups are species-specific. BRCA2 resolves in homo_sapiens; the mouse ortholog is Brca2 in mus_musculus.
• Not sure about a symbol? Use ids mode with the stable Ensembl ID - it is unambiguous and version-safe.
• Mixing species in one run is easy in ids mode: Ensembl IDs carry their own species prefix (ENSG, ENSMUSG, ENSDARG, ...).
• length is end - start in base pairs on the reference assembly.

Related actors

Building a life-sciences data pipeline? These pair well with this one:

• UniProt Scraper - protein entries, sequences, functions and cross-references.
• RCSB PDB Scraper - 3D protein structures and experimental metadata.
• ChEMBL Scraper - bioactive molecules, targets and assay data.
• PubMed Scraper - biomedical literature, abstracts and metadata.

Data source & attribution

Data comes from the public Ensembl REST API (EMBL-EBI / Wellcome Sanger Institute), which is free to use without an API key. Please cite Ensembl in publications and respect their fair-use policy (~15 requests/second) - this actor already paces itself accordingly.

Local development

pip install -r requirements.txt
python -m src.main
python tests/test_smoke.py   # offline smoke tests, no network needed