ucsc-browser

Query the UCSC Genome Browser REST API

When to Use

• User wants to query the UCSC Genome Browser REST API for tracks, sequences, or cCRE annotations
• User asks about "UCSC", "genome browser", "cCREs", "track hub", or "sequence retrieval"
• User needs to retrieve DNA sequences for peak regions or regulatory elements
• User wants to intersect ENCODE peaks with UCSC-hosted annotations (cCREs, conservation, repeat masker)
• Example queries: "get cCRE annotations for my region", "fetch DNA sequence under my peaks", "query UCSC for conservation scores at my enhancers"

Retrieve regulatory annotations, DNA sequences, TF binding data, and ENCODE-hosted tracks from the UCSC Genome Browser programmatic interface.

Scientific Rationale

The question: "What regulatory annotations exist at this genomic locus, and what is the underlying sequence?"

The UCSC Genome Browser hosts the most comprehensive collection of genome annotations, including ENCODE cCREs (926,535 human), TF rPeak clusters (21.8M from 912 factors across 1,152 biosamples), DNase clusters, conservation scores, and gene models. The REST API at api.genome.ucsc.edu enables programmatic access without authentication.

Why UCSC Complements the ENCODE Portal

The ENCODE Portal (encodeproject.org) provides experiment-level data — individual ChIP-seq peaks, BAM files, quality metrics. UCSC provides aggregated, cross-experiment annotations: which cCREs overlap your region, which TFs bind there across all ENCODE biosamples, and what the underlying DNA sequence is. Together they answer: "What did ENCODE find at this locus?" (UCSC) and "What are the specific experiments behind it?" (ENCODE Portal).

Literature Support

• ENCODE Project Consortium 2020 (Nature, ~1,656 citations): Registry of 926,535 human cCREs hosted on UCSC as encodeCcreCombined track. DOI
• Nassar et al. 2023 (Nucleic Acids Research): The UCSC Genome Browser database: 2023 update. DOI
• ENCODE4 TF Atlas: 21.8M TF rPeak clusters from 912 factors in 1,152 biosamples, hosted as TFrPeakClusters track on UCSC.

API Reference

Base URL: https://api.genome.ucsc.edu

No authentication required. Rate limit: ~1 request/second recommended. Use semicolons (;) to separate parameters.

Coordinate system: Half-open, 0-based start (matches BED format). start=1000000;end=1000100 returns 100 bases starting at position 1,000,000.

Step 1: Discover Available Tracks

Before querying data, check what tracks exist for your assembly:

# List all tracks for hg38
curl "https://api.genome.ucsc.edu/list/tracks?genome=hg38"

# Search for ENCODE-specific tracks
curl "https://api.genome.ucsc.edu/search?search=encode+regulation&genome=hg38&categories=trackDb"

# Get schema (field definitions) for a track
curl "https://api.genome.ucsc.edu/list/schema?genome=hg38;track=encodeCcreCombined"

Key ENCODE Tracks on UCSC (hg38)

| Track ID | Description | Data Type | Source | |----------|-------------|-----------|--------| | encodeCcreCombined | 926,535 candidate cis-regulatory elements (V3) | bigBed 9+ | ENCODE Phase 3 | | TFrPeakClusters | 21.8M TF rPeak clusters, 912 factors, 1,152 biosamples | bigBed 12+ | ENCODE 4 | | wgEncodeRegDnaseClustered | 2.1M+ DNase clusters across 95 cell types | MySQL table | ENCODE 2/3 | | wgEncodeRegTfbsClustered | TF binding site clusters (legacy) | MySQL table | ENCODE 2/3 |

Key Non-ENCODE Regulatory Tracks

| Track ID | Description | Use Case | |----------|-------------|----------| | cpgIslandExt | CpG islands | Promoter identification | | rmsk | RepeatMasker | Filter repetitive elements | | snp155 | dbSNP 155 with ClinVar | Variant annotation | | phastCons100way | Conservation scores (100 vertebrates) | Evolutionary constraint | | phyloP100way | Per-base conservation (100 vertebrates) | Variant impact |

Step 2: Query ENCODE cCREs at a Locus

The most common use case — what regulatory elements does ENCODE predict at this region?

# Get all cCREs in a 100kb window
curl "https://api.genome.ucsc.edu/getData/track?genome=hg38;track=encodeCcreCombined;chrom=chr1;start=1000000;end=1100000"

# Use jsonOutputArrays for named fields (recommended)
curl "https://api.genome.ucsc.edu/getData/track?genome=hg38;track=encodeCcreCombined;chrom=chr1;start=1000000;end=1100000;jsonOutputArrays=1"

Response Fields (encodeCcreCombined)

| Field | Description | Example | |-------|-------------|---------| | chrom | Chromosome | chr1 | | chromStart | Start (0-based) | 999856 | | chromEnd | End | 1000009 | | name | ENCODE accession | EH38E1310344 | | score | Signal strength (0-1000) | 312 | | encodeLabel | cCRE class | PLS, pELS, dELS, CTCF-only | | zScore | Max DNase Z-score | 3.1283 | | ccre | Full classification | PLS,CTCF-bound |

cCRE Classification Key

| Class | Full Name | Biochemical Signature | |-------|-----------|----------------------| | PLS | Promoter-like signature | DNase+ H3K4me3+ near TSS | | pELS | Proximal enhancer-like | DNase+ H3K27ac+ within 2kb of TSS | | dELS | Distal enhancer-like | DNase+ H3K27ac+ >2kb from TSS | | CTCF-only | CTCF-only | DNase+ CTCF+ (no H3K4me3/H3K27ac) | | DNase-H3K4me3 | DNase-H3K4me3 | DNase+ H3K4me3+ >200bp from TSS |

Step 3: Query TF Binding at a Locus

Which transcription factors bind at your region across all ENCODE biosamples?

# Get TF rPeak clusters in a region
curl "https://api.genome.ucsc.edu/getData/track?genome=hg38;track=TFrPeakClusters;chrom=chr1;start=1000000;end=1100000;jsonOutputArrays=1"

Response Fields (TFrPeakClusters)

| Field | Description | |-------|-------------| | factor | Transcription factor name (e.g., CTCF, POLR2A) | | ubiquity | Fraction of experiments showing binding (0-1) | | cCRE | Overlapping cCRE accession | | exp | ENCODE experiment accessions (links to Portal) |

Cross-reference with ENCODE Portal: The exp field contains ENCODE experiment accessions. Use encode_get_experiment to get full metadata:

encode_get_experiment(accession="ENCSR...")

Step 4: Retrieve DNA Sequence

Get the underlying DNA sequence for regulatory elements:

# Get sequence for a region
curl "https://api.genome.ucsc.edu/getData/sequence?genome=hg38;chrom=chr1;start=1000000;end=1000500"

# Get reverse complement
curl "https://api.genome.ucsc.edu/getData/sequence?genome=hg38;chrom=chr1;start=1000000;end=1000500;revComp=1"

Response includes a dna field with the nucleotide sequence.

Use cases for sequence retrieval:

• Extract sequence under ENCODE peaks for motif analysis (HOMER, MEME)
• Get sequence for CRISPR guide design at regulatory elements
• Check for known TF binding motifs at variants of interest
• Verify sequence context around GWAS variants

Step 5: Query DNase Accessibility Across Cell Types

# DNase clusters (95 cell types)
curl "https://api.genome.ucsc.edu/getData/track?genome=hg38;track=wgEncodeRegDnaseClustered;chrom=chr1;start=1000000;end=1100000;jsonOutputArrays=1"

The sourceCount field tells you how many of the 95 cell types show accessibility at each site — a measure of how constitutive vs tissue-specific the element is.

Step 6: Bulk Data Access with Command-Line Tools

For genome-wide queries, use UCSC command-line utilities instead of the REST API (which caps at 1M items):

# Download UCSC tools (macOS example)
# Available at: https://hgdownload.gi.ucsc.edu/admin/exe/

# Extract ENCODE cCREs for a region from hosted bigBed
bigBedToBed https://hgdownload.gi.ucsc.edu/gbdb/hg38/encode3/encodeCcreCombined.bb \
  -chrom=chr1 -start=1000000 -end=2000000 stdout

# Extract TF rPeak clusters
bigBedToBed https://hgdownload.gi.ucsc.edu/gbdb/hg38/bbi/ENCODE4/TFrPeakClusters.bb \
  -chrom=chr1 -start=1000000 -end=2000000 stdout

# Summarize bigWig signal over regions
bigWigSummary ht