claude-scientific-skills/scientific-skills/gtex-database/references/api_reference.md

GTEx API v2 Reference

Base URL

https://gtexportal.org/api/v2/

All endpoints accept GET requests. Responses are JSON. No authentication required.

Common Query Parameters

Parameter	Description	Example
gencodeId	GENCODE gene ID with version	ENSG00000130203.10
geneSymbol	Gene symbol	APOE
variantId	GTEx variant ID	chr17_45413693_C_T_b38
tissueSiteDetailId	Tissue identifier	Whole_Blood
datasetId	Dataset version	gtex_v10
itemsPerPage	Results per page	250
page	Page number (0-indexed)	0

Endpoint Reference

Expression Endpoints

GET /expression/medianGeneExpression

Median TPM expression for a gene across tissues.

Parameters: gencodeId, datasetId, itemsPerPage

Response fields:

{
  "data": [
    {
      "gencodeId": "ENSG00000130203.10",
      "geneSymbol": "APOE",
      "tissueSiteDetailId": "Liver",
      "tissueSiteDetail": "Liver",
      "median": 2847.9,
      "unit": "TPM",
      "datasetId": "gtex_v10"
    }
  ]
}

GET /expression/geneExpression

Full expression distribution (box plot data) per tissue.

Parameters: gencodeId, tissueSiteDetailId, datasetId

Response fields:

• data[].tissueExpressionData.data: array of TPM values per sample

Association (QTL) Endpoints

GET /association/singleTissueEqtl

Significant single-tissue cis-eQTLs.

Parameters: gencodeId OR variantId, tissueSiteDetailId (optional), datasetId

Response fields:

{
  "data": [
    {
      "gencodeId": "ENSG00000169174.14",
      "geneSymbol": "PCSK9",
      "variantId": "chr1_55516888_G_GA_b38",
      "snpId": "rs72646508",
      "tissueSiteDetailId": "Liver",
      "slope": -0.342,
      "slopeStandardError": 0.051,
      "pval": 3.2e-11,
      "qval": 2.1e-8,
      "maf": 0.089,
      "datasetId": "gtex_v10"
    }
  ]
}

Key fields:

• slope: effect of alt allele on expression (log2 scale after rank normalization)
• pval: nominal p-value
• qval: FDR-adjusted q-value
• maf: minor allele frequency in the GTEx cohort

GET /association/singleTissueSqtl

Significant single-tissue sQTLs (splicing).

Parameters: Same as eQTL endpoint

GET /association/egene

All eGenes (genes with ≥1 significant eQTL) in a tissue.

Parameters: tissueSiteDetailId, datasetId

Response fields: gene ID, gene symbol, best eQTL variant, p-value, q-value

Dataset/Metadata Endpoints

GET /dataset/tissueSiteDetail

List of all available tissues.

Parameters: datasetId, itemsPerPage

Response fields:

• tissueSiteDetailId: API identifier (use this in queries)
• tissueSiteDetail: Display name
• colorHex: Color for visualization
• samplingSite: Anatomical location

GET /reference/gene

Gene metadata from GENCODE.

Parameters: geneSymbol OR gencodeId, referenceGenomeId (GRCh38)

Variant Endpoints

GET /variant/variantPage

Variant metadata and lookup.

Parameters: snpId (rsID) OR variantId

Tissue IDs Reference (Common Tissues)

ID	Display Name
Whole_Blood	Whole Blood
Brain_Cortex	Brain - Cortex
Brain_Hippocampus	Brain - Hippocampus
Brain_Frontal_Cortex_BA9	Brain - Frontal Cortex (BA9)
Liver	Liver
Kidney_Cortex	Kidney - Cortex
Heart_Left_Ventricle	Heart - Left Ventricle
Lung	Lung
Muscle_Skeletal	Muscle - Skeletal
Adipose_Subcutaneous	Adipose - Subcutaneous
Colon_Transverse	Colon - Transverse
Small_Intestine_Terminal_Ileum	Small Intestine - Terminal Ileum
Skin_Sun_Exposed_Lower_leg	Skin - Sun Exposed (Lower leg)
Thyroid	Thyroid
Nerve_Tibial	Nerve - Tibial
Artery_Coronary	Artery - Coronary
Artery_Aorta	Artery - Aorta
Pancreas	Pancreas
Pituitary	Pituitary
Spleen	Spleen
Prostate	Prostate
Ovary	Ovary
Uterus	Uterus
Testis	Testis

Error Handling

import requests
from requests.exceptions import HTTPError, Timeout

def safe_gtex_query(endpoint, params):
    url = f"https://gtexportal.org/api/v2/{endpoint}"
    try:
        response = requests.get(url, params=params, timeout=30)
        response.raise_for_status()
        return response.json()
    except HTTPError as e:
        print(f"HTTP error {e.response.status_code}: {e.response.text}")
    except Timeout:
        print("Request timed out")
    except Exception as e:
        print(f"Error: {e}")
    return None

Rate Limiting

GTEx API does not publish explicit rate limits but:

• Add 0.5–1s delays between bulk queries
• Use data downloads for genome-wide analyses instead of API
• Cache results locally for repeated queries