Query the Ensembl REST API

When to Use

• User wants to annotate variants with Ensembl VEP (Variant Effect Predictor) consequences
• User asks about "VEP", "Ensembl", "variant annotation", "regulatory build", or "gene annotation"
• User needs to convert coordinates between assemblies using Ensembl's liftover API
• User wants to check the Ensembl Regulatory Build for overlap with ENCODE elements
• Example queries: "run VEP on my variant list", "annotate SNPs with regulatory consequences", "check Ensembl regulatory build for my peaks"

Annotate variants, look up regulatory features, convert coordinates, and resolve gene identifiers using the Ensembl REST API.

Scientific Rationale

The question: "What does the Ensembl Regulatory Build say about this region, and what is the predicted effect of this variant?"

The Ensembl Regulatory Build integrates ENCODE, Roadmap Epigenomics, and Blueprint data into a unified annotation of regulatory features across human cell types. The Variant Effect Predictor (VEP) is the standard tool for variant consequence prediction, integrating 50+ annotation sources including CADD, REVEL, SpliceAI, and AlphaMissense.

Ensembl ↔ ENCODE Feedback Loop

Ensembl's Regulatory Build incorporates ENCODE ChIP-seq, DNase-seq, and CTCF data to define regulatory features. Querying Ensembl after an ENCODE analysis provides an independent, aggregated view of regulatory annotations — often including data from non-ENCODE sources (Blueprint, Roadmap) that may cover biosamples not in ENCODE.

Literature Support

• Cunningham et al. 2022 (Nucleic Acids Research): Ensembl 2022 update. DOI
• McLaren et al. 2016 (Genome Biology, ~4,500 citations): The Ensembl Variant Effect Predictor. DOI
• Zerbino et al. 2015 (Genome Biology): The Ensembl Regulatory Build. DOI

API Reference

Base URL: https://rest.ensembl.org Authentication: None required Rate limit: Reasonable use expected; max 5Mb region queries Formats: JSON (default), XML, GFF3, BED Current version: Ensembl 114

Add content-type: application/json header to all requests.

Step 1: Regulatory Feature Overlap

Query what regulatory features the Ensembl Regulatory Build assigns to a region:

# Get regulatory features in a region
curl -H "Content-type: application/json" \
  "https://rest.ensembl.org/overlap/region/human/7:140424943-140624564?feature=regulatory"

# Also get TF binding motifs
curl -H "Content-type: application/json" \
  "https://rest.ensembl.org/overlap/region/human/7:140424943-140624564?feature=regulatory;feature=motif"

Regulatory Feature Types

Type	Description	ENCODE Equivalent
Promoter	Active promoter region	cCRE PLS
Enhancer	Active enhancer region	cCRE pELS/dELS
Open chromatin	Accessible region without H3K27ac	DNase-only sites
CTCF binding site	CTCF-occupied region	cCRE CTCF-only
TF binding site	Other TF binding	TF ChIP-seq peaks
Promoter flanking	Region flanking a promoter	cCRE TssAFlnk

Step 2: Variant Effect Prediction (VEP)

VEP provides consequence predictions for variants:

Single Variant (by region notation)

# VEP annotation for a variant
curl -H "Content-type: application/json" \
  "https://rest.ensembl.org/vep/human/region/9:22125503-22125502:1/C"

# By rs ID
curl -H "Content-type: application/json" \
  "https://rest.ensembl.org/vep/human/id/rs699"

Batch VEP (POST, up to 200 variants)

curl -X POST -H "Content-type: application/json" \
  "https://rest.ensembl.org/vep/human/region" \
  -d '{"variants": ["1 230710048 . A G . . .", "2 241533886 . T C . . ."]}'

Key VEP Parameters

Parameter	Description	Default
CADD=1	Include CADD scores	Off
Enformer=1	Include Enformer predictions	Off
AlphaMissense=1	Include AlphaMissense pathogenicity	Off
REVEL=1	Include REVEL scores	Off
SpliceAI=1	Include SpliceAI splicing predictions	Off
regulatory=1	Include regulatory feature overlap	Off
cell_type=	Cell type for regulatory annotations	All

VEP Consequence Hierarchy (most to least severe)

Consequence	Impact	Description
transcript_ablation	HIGH	Deletion of entire transcript
splice_donor_variant	HIGH	Essential splice donor site
stop_gained	HIGH	Premature stop codon
frameshift_variant	HIGH	Reading frame change
missense_variant	MODERATE	Amino acid change
splice_region_variant	LOW	Near splice site
synonymous_variant	LOW	No amino acid change
regulatory_region_variant	MODIFIER	In regulatory element
intergenic_variant	MODIFIER	Between genes

For ENCODE regulatory variants: Most will be classified as regulatory_region_variant (MODIFIER impact). The VEP consequence alone does not capture regulatory impact — combine with ENCODE cCRE class, tissue activity, and TF disruption data.

Step 3: Coordinate Conversion (LiftOver)

Convert between GRCh37 (hg19) and GRCh38 (hg38):

# GRCh37 → GRCh38
curl -H "Content-type: application/json" \
  "https://rest.ensembl.org/map/human/GRCh37/17:1000000..1000100:1/GRCh38"

# GRCh38 → GRCh37
curl -H "Content-type: application/json" \
  "https://rest.ensembl.org/map/human/GRCh38/17:1000000..1000100:1/GRCh37"

When needed: Older GWAS studies report variants on GRCh37. ENCODE data uses GRCh38. Always liftOver before intersecting.

Step 4: Gene Lookup and Cross-References

Gene Information

# By Ensembl ID
curl -H "Content-type: application/json" \
  "https://rest.ensembl.org/lookup/id/ENSG00000157764?expand=1"

# By symbol
curl -H "Content-type: application/json" \
  "https://rest.ensembl.org/lookup/symbol/homo_sapiens/BRAF"

Cross-References (Ensembl ↔ External DBs)

# Get all external references for a gene
curl -H "Content-type: application/json" \
  "https://rest.ensembl.org/xrefs/id/ENSG00000157764"

# Filter by external DB
curl -H "Content-type: application/json" \
  "https://rest.ensembl.org/xrefs/id/ENSG00000157764?external_db=HGNC"

ENCODE integration: ENCODE target names are typically HGNC symbols or Ensembl IDs. Use this endpoint to resolve between identifier systems.

Step 5: Phenotype/Disease Associations

# Get phenotype associations for a gene
curl -H "Content-type: application/json" \
  "https://rest.ensembl.org/phenotype/gene/homo_sapiens/BRCA2"

# Get phenotype associations for a region
curl -H "Content-type: application/json" \
  "https://rest.ensembl.org/phenotype/region/homo_sapiens/9:22125500-22136000"

Integrated ENCODE + Ensembl Workflow

1. Find ENCODE regulatory variants:
   → Intersect GWAS variants with ENCODE cCREs

2. Annotate with VEP:
   curl "https://rest.ensembl.org/vep/human/id/rs699?CADD=1;regulatory=1;REVEL=1"
   → Get consequence, CADD score, regulatory overlap

3. Check Ensembl Regulatory Build for independent confirmation:
   curl "https://rest.ensembl.org/overlap/region/human/CHR:START-END?feature=regulatory"
   → Compare with ENCODE cCRE classification

4. If working with GRCh37 data, liftOver:
   curl "https://rest.ensembl.org/map/human/GRCh37/CHR:POS..POS:1/GRCh38"

5. Resolve gene identifiers for ENCODE targets:
   curl "https://rest.ensembl.org/lookup/symbol/homo_sapiens/GENE_SYMBOL"

6. Check disease associations:
   curl "https://rest.ensembl.org/phenotype/gene/homo_sapiens/GENE"

Pitfalls and Caveats

1. Ensembl Regulatory Build ≠ ENCODE cCREs: The Regulatory Build incorporates ENCODE data but uses different classification criteria. Annotations may not perfectly overlap with ENCODE cCRE calls.
2. VEP MODIFIER impact for regulatory variants: Non-coding regulatory variants are classified as MODIFIER impact by default. This does NOT mean low importance — it means VEP cannot assess regulatory consequence from sequence alone. Combine with ENCODE data.
3. Region size limits: Overlap queries limited to ~5Mb regions. For genome-wide analysis, download Ensembl GFF files or use the Perl VEP tool locally.
4. Batch VEP limit: REST API accepts max 200 variants per POST request. For larger sets, use the standalone VEP tool.
5. GRCh38/GRCh37 consistency: Always match assembly between ENCODE data and Ensembl queries. Use the liftOver endpoint when needed.
6. Version updates: Ensembl releases quarterly. Regulatory Build annotations may change between versions. Note the Ensembl version in your analysis.

Walkthrough: Variant Effect Prediction for ENCODE Regulatory Variants

Goal: Use Ensembl VEP to predict functional consequences of variants located within ENCODE-defined regulatory elements, combining variant annotation with regulatory context. Context: Ensembl provides the gold-standard Variant Effect Predictor (VEP) and Regulatory Build. Combined with ENCODE peaks, this enables comprehensive variant interpretation.

Step 1: Find ENCODE experiments for the tissue of interest

encode_search_experiments(assay_title="ATAC-seq", organ="brain", organism="Homo sapiens")

Expected output:

{
  "results": [
    {"accession": "ENCSR800BRN", "assay_title": "ATAC-seq", "biosample_summary": "brain tissue male adult (54 years)", "assembly": ["GRCh38"], "status": "released"}
  ],
  "total": 32,
  "limit": 25,
  "offset": 0,
  "has_more": true,
  "next_offset": 25
}

Step 2: Download peaks and extract variants

encode_download_files(file_accessions=["ENCFF900ATK"], download_dir="/data/brain_atac")

Step 3: Run VEP on regulatory variants

Using Ensembl REST API (via skill guidance):

POST https://rest.ensembl.org/vep/human/region
Content-Type: application/json
{"variants": ["1 230710048 . A G", "7 87160618 . T C"]}

Expected VEP output:

[
  {
    "input": "1 230710048 . A G",
    "most_severe_consequence": "regulatory_region_variant",
    "regulatory_feature_consequences": [
      {
        "regulatory_feature_id": "ENSR00000123456",
        "biotype": "promoter",
        "consequence_terms": ["regulatory_region_variant"]
      }
    ]
  }
]

Interpretation: VEP classifies this as a regulatory_region_variant in an Ensembl Regulatory Build promoter. Cross-referencing with the ENCODE ATAC-seq peak confirms the variant is in open chromatin in brain tissue.

Step 4: Liftover if needed

If ENCODE peaks are in GRCh38 but variants are in hg19:

• Use → liftover-coordinates to convert variant positions before intersection
• Or use Ensembl REST API liftover endpoint

Step 5: Integrate Ensembl Regulatory Build with ENCODE peaks

GET https://rest.ensembl.org/regulatory/species/homo_sapiens/id/ENSR00000123456

Interpretation: Compare Ensembl Regulatory Build activity with ENCODE experimental data. If the Regulatory Build calls a region a "promoter" and ENCODE H3K4me3 ChIP-seq confirms this, the annotation is high confidence.

Integration with downstream skills

• ENCODE peaks define regions to annotate via → VEP regulatory consequence prediction
• VEP results feed into → variant-annotation for multi-source annotation
• Regulatory Build comparisons inform → regulatory-elements cCRE classification
• Gene consequence predictions connect to → gtex-expression for expression validation
• Coordinate conversions handled by → liftover-coordinates for cross-assembly work

Code Examples

1. Find ENCODE data for an Ensembl-annotated gene

# Step 1: Identify the gene's regulatory neighborhood
# (via Ensembl REST API — see skill instructions)

# Step 2: Search ENCODE for ChIP-seq at the gene locus
encode_search_experiments(
  assay_title="Histone ChIP-seq",
  organ="liver",
  target="H3K27ac"
)

Expected output:

{
  "results": [
    {
      "accession": "ENCSR123ABC",
      "assay_title": "Histone ChIP-seq",
      "target": "H3K27ac-human",
      "biosample_summary": "liver tissue male adult (54 years)"
    }
  ],
  "total": 8,
  "limit": 25,
  "offset": 0,
  "has_more": false,
  "next_offset": null
}

2. Track and cross-reference an annotated experiment

encode_track_experiment(
  accession="ENCSR123ABC",
  notes="Liver H3K27ac for VEP-annotated enhancer variants"
)

Expected output:

{
  "tracking": {"accession": "ENCSR123ABC", "action": "tracked"},
  "publications_found": 1,
  "publications": [
    {
      "pmid": "32728249",
      "doi": "10.1038/s41586-020-2493-4",
      "title": "An atlas of gene regulatory elements in adult human liver",
      "authors": "Li YE, Preissl S, Hou X",
      "journal": "Nature",
      "year": "2020",
      "abstract": ""
    }
  ],
  "pipelines_found": 1,
  "pipelines": [
    {"title": "Histone ChIP-seq 2 (unreplicated)", "version": "1.7.1", "software": [{"name": "bowtie2", "version": "2.3.4.3"}], "status": "released"}
  ]
}

Integration

This skill produces...	Feed into...	Using tool/skill
VEP-annotated variant list	Regulatory variant filtering	variant-annotation skill
Gene annotations with coordinates	Peak-to-gene assignment	peak-annotation skill
Lifted-over coordinates (GRCh37→38)	ENCODE data integration	liftover-coordinates skill
Regulatory Build overlap results	Enhancer/promoter classification	regulatory-elements skill
Gene constraint scores	Target prioritization	cross-reference → Open Targets

Related Skills

Skill	When to Use Instead/Additionally
variant-annotation	Full ENCODE-based post-GWAS workflow
gnomad-variants	Population frequency and constraint data for variants
regulatory-elements	ENCODE cCRE classification and chromatin state analysis
ucsc-browser	UCSC-hosted ENCODE tracks and sequence retrieval
disease-research	Connecting variants to disease mechanisms
cross-reference	General external database cross-referencing
publication-trust	Verify literature claims backing analytical decisions

Presenting Results

• Present gene annotations as: gene | ensembl_id | biotype | chr:start-end | strand. Include transcript count. Suggest: "Would you like to check expression in GTEx for these genes?"

For the request: "$ARGUMENTS"