Skip to content

Coverage search

With the Coverage search API, you can search a genomic region or a pasted DNA sequence and retrieve per-group read coverage, with the same data that drives the Coverage Explorer browser.

The workflow mirrors the Expression API:

  1. POST /api/coverage/submit returns a search_job_id.
  2. Poll GET /api/coverage/status/<search_job_id> until completed.
  3. POST /api/coverage/results/<search_job_id> returns the coverage matrix.

Endpoints

Method Path Auth Purpose
GET /api/coverage/genome-info Public Genome availability and reference
GET /api/coverage/gene-lookup Public Resolve a gene name to coordinates
POST /api/coverage/submit Required Submit a region or sequence search
GET /api/coverage/status/<search_job_id> Required Poll search progress
POST /api/coverage/results/<search_job_id> Required Coverage matrix and probe data
POST /api/coverage/sample-metadata Required Metadata for a set of sample IDs
GET /api/coverage/available-filters Public Available metadata filters

Genome reference

curl https://malva.mdc-berlin.de/api/coverage/genome-info

{"available": true, "chromosomes": ["chr1", "chr2"], "window_size": 48}

The window_size is the smallest genomic window the search engine supports (48 base pairs).

Resolve a gene to coordinates

curl "https://malva.mdc-berlin.de/api/coverage/gene-lookup?gene=TP53&genome=hg38"

Returns {position, gene, matched_name, track} when the gene resolves. Use the position in a region search. The lookup proxies the UCSC REST service, so an unknown gene returns 404.

The body switches on mode:

curl -X POST https://malva.mdc-berlin.de/api/coverage/submit \
  -H "Authorization: Bearer malva_..." \
  -H "Content-Type: application/json" \
  -d '{"mode": "region", "region": "chr1:1000000-2000000"}'

A region spans at least 48 base pairs and at most 10 megabases.

curl -X POST https://malva.mdc-berlin.de/api/coverage/submit \
  -H "Authorization: Bearer malva_..." \
  -H "Content-Type: application/json" \
  -d '{"mode": "sequence", "sequence": "ACGTACGTACGT..."}'

A sequence spans at least 48 base pairs and at most 1 megabase, and may contain the letters A, C, G, T and N.

Response:

{
  "search_job_id": "coverage-job-uuid",
  "positions": ["chr1:1000000", "chr1:1000048"],
  "sequences": ["ACGT..."],
  "region": "chr1:1000000-1000480",
  "num_probes": 10,
  "status": "running"
}

The server slides a 48-base-pair window across the region or sequence and submits each window as a probe. Each submission consumes one unit of your daily quota.

Poll the status

curl https://malva.mdc-berlin.de/api/coverage/status/<search_job_id> \
  -H "Authorization: Bearer malva_..."

{"status": "running", "progress": 0.4, "stage": "searching", "step_description": "..."}

Read the coverage matrix

curl -X POST https://malva.mdc-berlin.de/api/coverage/results/<search_job_id> \
  -H "Authorization: Bearer malva_..." \
  -H "Content-Type: application/json" \
  -d '{"positions": ["chr1:1000000"], "filters": {"cell_types": ["T cell"]}}'

{
  "status": "completed",
  "coverage": {...},
  "probe_data": {...}
}

coverage holds the per-group coverage matrix: each row is a cell group defined by the active metadata columns, and each column a probe position. probe_data describes the probes. Pass filters to restrict the result to specific cell types, as the web interface does.

Sample metadata

curl -X POST https://malva.mdc-berlin.de/api/coverage/sample-metadata \
  -H "Authorization: Bearer malva_..." \
  -H "Content-Type: application/json" \
  -d '{"ids": [1, 2, 3]}'

Returns {"metadata": {...}} for the sample IDs in the coverage result.

Compatibility routes

The malva_client package uses an additional set of coverage routes:

Method Path Purpose
POST /api/genome-browser/search Region search with {chromosome, start, end, strand, zoom_level, metadata_filters?}
POST /api/genome-browser/search-sequence Sequence search with {sequence, sequence_name?, metadata_filters?}
GET /api/genome-browser/coverage/<job_id> Processed coverage data
GET /api/genome-browser/coverage-compact/<job_id> Compact coverage, msgpack stream
GET /api/genome-browser/coverage-file/<job_id> WIG file download (coverage_<job_id>.wig)
GET /api/genome-browser/filter-options/<job_id> Cell types in a coverage job

These return the same data as the native routes; use the native routes for new integrations.