ClinPGx Database

Overview

ClinPGx (Clinical Pharmacogenomics Database) is a comprehensive resource for clinical pharmacogenomics information, successor to PharmGKB. It consolidates data from PharmGKB, CPIC, and PharmCAT, providing curated information on how genetic variation affects medication response. Access gene-drug pairs, clinical guidelines, allele functions, and drug labels for precision medicine applications.

When to Use This Skill

This skill should be used when:

Gene-drug interactions: Querying how genetic variants affect drug metabolism, efficacy, or toxicity
CPIC guidelines: Accessing evidence-based clinical practice guidelines for pharmacogenetics
Allele information: Retrieving allele function, frequency, and phenotype data
Drug labels: Exploring FDA and other regulatory pharmacogenomic drug labeling
Pharmacogenomic annotations: Accessing curated literature on gene-drug-disease relationships
Clinical decision support: Using PharmDOG tool for phenoconversion and custom genotype interpretation
Precision medicine: Implementing pharmacogenomic testing in clinical practice
Drug metabolism: Understanding CYP450 and other pharmacogene functions
Personalized dosing: Finding genotype-guided dosing recommendations
Adverse drug reactions: Identifying genetic risk factors for drug toxicity

Installation and Setup

Python API Access

The ClinPGx REST API provides programmatic access to all database resources. Basic setup:

uv pip install requests

API Endpoint

BASE_URL = "https://api.clinpgx.org/v1/"

Rate Limits:

2 requests per second maximum
Excessive requests will result in HTTP 429 (Too Many Requests) response

Authentication: Not required for basic access

Data License: Creative Commons Attribution-ShareAlike 4.0 International License

For substantial API use, notify the ClinPGx team at [email protected]

Core Capabilities

1. Gene Queries

Retrieve gene information including function, clinical annotations, and pharmacogenomic significance:

import requests

# Get gene details
response = requests.get("https://api.clinpgx.org/v1/gene/CYP2D6")
gene_data = response.json()

# Search for genes by name
response = requests.get("https://api.clinpgx.org/v1/gene",
                       params={"q": "CYP"})
genes = response.json()

Key pharmacogenes:

CYP450 enzymes: CYP2D6, CYP2C19, CYP2C9, CYP3A4, CYP3A5
Transporters: SLCO1B1, ABCB1, ABCG2
Other metabolizers: TPMT, DPYD, NUDT15, UGT1A1
Receptors: OPRM1, HTR2A, ADRB1
HLA genes: HLA-B, HLA-A

2. Drug and Chemical Queries

Retrieve drug information including pharmacogenomic annotations and mechanisms:

# Get drug details
response = requests.get("https://api.clinpgx.org/v1/chemical/PA448515")  # Warfarin
drug_data = response.json()

# Search drugs by name
response = requests.get("https://api.clinpgx.org/v1/chemical",
                       params={"name": "warfarin"})
drugs = response.json()

Drug categories with pharmacogenomic significance:

Anticoagulants (warfarin, clopidogrel)
Antidepressants (SSRIs, TCAs)
Immunosuppressants (tacrolimus, azathioprine)
Oncology drugs (5-fluorouracil, irinotecan, tamoxifen)
Cardiovascular drugs (statins, beta-blockers)
Pain medications (codeine, tramadol)
Antivirals (abacavir)

3. Gene-Drug Pair Queries

Access curated gene-drug relationships with clinical annotations:

# Get gene-drug pair information
response = requests.get("https://api.clinpgx.org/v1/geneDrugPair",
                       params={"gene": "CYP2D6", "drug": "codeine"})
pair_data = response.json()

# Get all pairs for a gene
response = requests.get("https://api.clinpgx.org/v1/geneDrugPair",
                       params={"gene": "CYP2C19"})
all_pairs = response.json()

Clinical annotation sources:

CPIC (Clinical Pharmacogenetics Implementation Consortium)
DPWG (Dutch Pharmacogenetics Working Group)
FDA (Food and Drug Administration) labels
Peer-reviewed literature summary annotations

4. CPIC Guidelines

Access evidence-based clinical practice guidelines:

# Get CPIC guideline
response = requests.get("https://api.clinpgx.org/v1/guideline/PA166104939")
guideline = response.json()

# List all CPIC guidelines
response = requests.get("https://api.clinpgx.org/v1/guideline",
                       params={"source": "CPIC"})
guidelines = response.json()

CPIC guideline components:

Gene-drug pairs covered
Clinical recommendations by phenotype
Evidence levels and strength ratings
Supporting literature
Downloadable PDFs and supplementary materials
Implementation considerations

Example guidelines:

CYP2D6-codeine (avoid in ultra-rapid metabolizers)
CYP2C19-clopidogrel (alternative therapy for poor metabolizers)
TPMT-azathioprine (dose reduction for intermediate/poor metabolizers)
DPYD-fluoropyrimidines (dose adjustment based on activity)
HLA-B*57:01-abacavir (avoid if positive)

5. Allele and Variant Information

Query allele function and frequency data:

# Get allele information
response = requests.get("https://api.clinpgx.org/v1/allele/CYP2D6*4")
allele_data = response.json()

# Get all alleles for a gene
response = requests.get("https://api.clinpgx.org/v1/allele",
                       params={"gene": "CYP2D6"})
alleles = response.json()

Allele information includes:

Functional status (normal, decreased, no function, increased, uncertain)
Population frequencies across ethnic groups
Defining variants (SNPs, indels, CNVs)
Phenotype assignment
References to PharmVar and other nomenclature systems

Phenotype categories:

Ultra-rapid metabolizer (UM): Increased enzyme activity
Normal metabolizer (NM): Normal enzyme activity
Intermediate metabolizer (IM): Reduced enzyme activity
Poor metabolizer (PM): Little to no enzyme activity

6. Variant Annotations

Access clinical annotations for specific genetic variants:

# Get variant information
response = requests.get("https://api.clinpgx.org/v1/variant/rs4244285")
variant_data = response.json()

# Search variants by position (if supported)
response = requests.get("https://api.clinpgx.org/v1/variant",
                       params={"chromosome": "10", "position": "94781859"})
variants = response.json()

Variant data includes:

rsID and genomic coordinates
Gene and functional consequence
Allele associations
Clinical significance
Population frequencies
Literature references

7. Clinical Annotations

Retrieve curated literature annotations (formerly PharmGKB clinical annotations):

# Get clinical annotations
response = requests.get("https://api.clinpgx.org/v1/clinicalAnnotation",
                       params={"gene": "CYP2D6"})
annotations = response.json()

# Filter by evidence level
response = requests.get("https://api.clinpgx.org/v1/clinicalAnnotation",
                       params={"evidenceLevel": "1A"})
high_evidence = response.json()

Evidence levels (from highest to lowest):

Level 1A: High-quality evidence, CPIC/FDA/DPWG guidelines
Level 1B: High-quality evidence, not yet guideline
Level 2A: Moderate evidence from well-designed studies
Level 2B: Moderate evidence with some limitations
Level 3: Limited or conflicting evidence
Level 4: Case reports or weak evidence

8. Drug Labels

Access pharmacogenomic information from drug labels:

# Get drug labels with PGx information
response = requests.get("https://api.clinpgx.org/v1/drugLabel",
                       params={"drug": "warfarin"})
labels = response.json()

# Filter by regulatory source
response = requests.get("https://api.clinpgx.org/v1/drugLabel",
                       params={"source": "FDA"})
fda_labels = response.json()

Label information includes:

Testing recommendations
Dosing guidance by genotype
Warnings and precautions
Biomarker information
Regulatory source (FDA, EMA, PMDA, etc.)

9. Pathways

Explore pharmacokinetic and pharmacodynamic pathways:

# Get pathway information
response = requests.get("https://api.clinpgx.org/v1/pathway/PA146123006")  # Warfarin pathway
pathway_data = response.json()

# Search pathways by drug
response = requests.get("https://api.clinpgx.org/v1/pathway",
                       params={"drug": "warfarin"})
pathways = response.json()

Pathway diagrams show:

Drug metabolism steps
Enzymes and transporters involved
Gene variants affecting each step
Downstream effects on efficacy/toxicity
Interactions with other pathways

Query Workflow

Workflow 1: Clinical Decision Support for Drug Prescription

Identify patient genotype for relevant pharmacogenes:

# Example: Patient is CYP2C19 *1/*2 (intermediate metabolizer)
response = requests.get("https://api.clinpgx.org/v1/allele/CYP2C19*2")
allele_function = response.json()

Query gene-drug pairs for medication of interest:

response = requests.get("https://api.clinpgx.org/v1/geneDrugPair",
                       params={"gene": "CYP2C19", "drug": "clopidogrel"})
pair_info = response.json()

Retrieve CPIC guideline for dosing recommendations:

response = requests.get("https://api.clinpgx.org/v1/guideline",
                       params={"gene": "CYP2C19", "drug": "clopidogrel"})
guideline = response.json()
# Recommendation: Alternative antiplatelet therapy for IM/PM

Check drug label for regulatory guidance:

response = requests.get("https://api.clinpgx.org/v1/drugLabel",
                       params={"drug": "clopidogrel"})
label = response.json()

Workflow 2: Gene Panel Analysis

Get list of pharmacogenes in clinical panel:

pgx_panel = ["CYP2C19", "CYP2D6", "CYP2C9", "TPMT", "DPYD", "SLCO1B1"]

For each gene, retrieve all drug interactions:

all_interactions = {}
for gene in pgx_panel:
    response = requests.get("https://api.clinpgx.org/v1/geneDrugPair",
                           params={"gene": gene})
    all_interactions[gene] = response.json()

Filter for CPIC guideline-level evidence:

for gene, pairs in all_interactions.items():
    for pair in pairs:
        if pair.get('cpicLevel'):  # Has CPIC guideline
            print(f"{gene} - {pair['drug']}: {pair['cpicLevel']}")

Generate patient report with actionable pharmacogenomic findings.

Workflow 3: Drug Safety Assessment

Query drug for PGx associations:

response = requests.get("https://api.clinpgx.org/v1/chemical",
                       params={"name": "abacavir"})
drug_id = response.json()[0]['id']

Get clinical annotations:

response = requests.get("https://api.clinpgx.org/v1/clinicalAnnotation",
                       params={"drug": drug_id})
annotations = response.json()

Check for HLA associations and toxicity risk:

for annotation in annotations:
    if 'HLA' in annotation.get('genes', []):
        print(f"Toxicity risk: {annotation['phenotype']}")
        print(f"Evidence level: {annotation['evidenceLevel']}")

Retrieve screening recommendations from guidelines and labels.

Workflow 4: Research Analysis - Population Pharmacogenomics

Get allele frequencies for population comparison:

response = requests.get("https://api.clinpgx.org/v1/allele",
                       params={"gene": "CYP2D6"})
alleles = response.json()

Extract population-specific frequencies:

populations = ['European', 'African', 'East Asian', 'Latino']
frequency_data = {}
for allele in alleles:
    allele_name = allele['name']
    frequency_data[allele_name] = {
        pop: allele.get(f'{pop}_frequency', 'N/A')
        for pop in populations
    }

Calculate phenotype distributions by population:

# Combine allele frequencies with function to predict phenotypes
phenotype_dist = calculate_phenotype_frequencies(frequency_data)

Analyze implications for drug dosing in diverse populations.

Workflow 5: Literature Evidence Review

Search for gene-drug pair:

response = requests.get("https://api.clinpgx.org/v1/geneDrugPair",
                       params={"gene": "TPMT", "drug": "azathioprine"})
pair = response.json()

Retrieve all clinical annotations:

response = requests.get("https://api.clinpgx.org/v1/clinicalAnnotation",
                       params={"gene": "TPMT", "drug": "azathioprine"})
annotations = response.json()

Filter by evidence level and publication date:

high_quality = [a for a in annotations
                if a['evidenceLevel'] in ['1A', '1B', '2A']]

Extract PMIDs and retrieve full references:

pmids = [a['pmid'] for a in high_quality if 'pmid' in a]
# Use PubMed skill to retrieve full citations

Rate Limiting and Best Practices

Rate Limit Compliance

import time

def rate_limited_request(url, params=None, delay=0.5):
    """Make API request with rate limiting (2 req/sec max)"""
    response = requests.get(url, params=params)
    time.sleep(delay)  # Wait 0.5 seconds between requests
    return response

# Use in loops
genes = ["CYP2D6", "CYP2C19", "CYP2C9"]
for gene in genes:
    response = rate_limited_request(
        "https://api.clinpgx.org/v1/gene/" + gene
    )
    data = response.json()

Error Handling

def safe_api_call(url, params=None, max_retries=3):
    """API call with error handling and retries"""
    for attempt in range(max_retries):
        try:
            response = requests.get(url, params=params, timeout=10)

            if response.status_code == 200:
                return response.json()
            elif response.status_code == 429:
                # Rate limit exceeded
                wait_time = 2 ** attempt  # Exponential backoff
                print(f"Rate limit hit. Waiting {wait_time}s...")
                time.sleep(wait_time)
            else:
                response.raise_for_status()

        except requests.exceptions.RequestException as e:
            print(f"Attempt {attempt + 1} failed: {e}")
            if attempt == max_retries - 1:
                raise
            time.sleep(1)

Caching Results

import json
from pathlib import Path

def cached_query(cache_file, api_func, *args, **kwargs):
    """Cache API results to avoid repeated queries"""
    cache_path = Path(cache_file)

    if cache_path.exists():
        with open(cache_path) as f:
            return json.load(f)

    result = api_func(*args, **kwargs)

    with open(cache_path, 'w') as f:
        json.dump(result, f, indent=2)

    return result

# Usage
gene_data = cached_query(
    'cyp2d6_cache.json',
    rate_limited_request,
    "https://api.clinpgx.org/v1/gene/CYP2D6"
)

PharmDOG Tool

PharmDOG (formerly DDRx) is ClinPGx's clinical decision support tool for interpreting pharmacogenomic test results:

Key features:

Phenoconversion calculator: Adjusts phenotype predictions for drug-drug interactions affecting CYP2D6
Custom genotypes: Input patient genotypes to get phenotype predictions
QR code sharing: Generate shareable patient reports
Flexible guidance sources: Select which guidelines to apply (CPIC, DPWG, FDA)
Multi-drug analysis: Assess multiple medications simultaneously

Access: Available at https://www.clinpgx.org/pharmacogenomic-decision-support

Use cases:

Clinical interpretation of PGx panel results
Medication review for patients with known genotypes
Patient education materials
Point-of-care decision support

Resources

scripts/query_clinpgx.py

Python script with ready-to-use functions for common ClinPGx queries:

get_gene_info(gene_symbol) - Retrieve gene details
get_drug_info(drug_name) - Get drug information
get_gene_drug_pairs(gene, drug) - Query gene-drug interactions
get_cpic_guidelines(gene, drug) - Retrieve CPIC guidelines
get_alleles(gene) - Get all alleles for a gene
get_clinical_annotations(gene, drug, evidence_level) - Query literature annotations
get_drug_labels(drug) - Retrieve pharmacogenomic drug labels
search_variants(rsid) - Search by variant rsID
export_to_dataframe(data) - Convert results to pandas DataFrame

Consult this script for implementation examples with proper rate limiting and error handling.

references/api_reference.md

Comprehensive API documentation including:

Complete endpoint listing with parameters
Request/response format specifications
Example queries for each endpoint
Filter operators and search patterns
Data schema definitions
Rate limiting details
Authentication requirements (if any)
Troubleshooting common errors

Refer to this document when detailed API information is needed or when constructing complex queries.

Important Notes

Data Sources and Integration

ClinPGx consolidates multiple authoritative sources:

PharmGKB: Curated pharmacogenomics knowledge base (now part of ClinPGx)
CPIC: Evidence-based clinical implementation guidelines
PharmCAT: Allele calling and phenotype interpretation tool
DPWG: Dutch pharmacogenetics guidelines
FDA/EMA labels: Regulatory pharmacogenomic information

As of July 2025, all PharmGKB URLs redirect to corresponding ClinPGx pages.

Clinical Implementation Considerations

Evidence levels: Always check evidence strength before clinical application
Population differences: Allele frequencies vary significantly across populations
Phenoconversion: Consider drug-drug interactions that affect enzyme activity
Multi-gene effects: Some drugs affected by multiple pharmacogenes
Non-genetic factors: Age, organ function, drug interactions also affect response
Testing limitations: Not all clinically relevant alleles detected by all assays

Data Updates

ClinPGx continuously updates with new evidence and guidelines
Check publication dates for clinical annotations
Monitor ClinPGx Blog (https://blog.clinpgx.org/) for announcements
CPIC guidelines updated as new evidence emerges
PharmVar provides nomenclature updates for allele definitions

API Stability

API endpoints are relatively stable but may change during development
Parameters and response formats subject to modification
Monitor API changelog and ClinPGx blog for updates
Consider version pinning for production applications
Test API changes in development before production deployment

Common Use Cases

Pre-emptive Pharmacogenomic Testing

Query all clinically actionable gene-drug pairs to guide panel selection:

# Get all CPIC guideline pairs
response = requests.get("https://api.clinpgx.org/v1/geneDrugPair",
                       params={"cpicLevel": "A"})  # Level A recommendations
actionable_pairs = response.json()

Medication Therapy Management

Review patient medications against known genotypes:

patient_genes = {"CYP2C19": "*1/*2", "CYP2D6": "*1/*1", "SLCO1B1": "*1/*5"}
medications = ["clopidogrel", "simvastatin", "escitalopram"]

for med in medications:
    for gene in patient_genes:
        response = requests.get("https://api.clinpgx.org/v1/geneDrugPair",
                               params={"gene": gene, "drug": med})
        # Check for interactions and dosing guidance

Clinical Trial Eligibility

Screen for pharmacogenomic contraindications:

# Check for HLA-B*57:01 before abacavir trial
response = requests.get("https://api.clinpgx.org/v1/geneDrugPair",
                       params={"gene": "HLA-B", "drug": "abacavir"})
pair_info = response.json()
# CPIC: Do not use if HLA-B*57:01 positive

Additional Resources

ClinPGx website: https://www.clinpgx.org/
ClinPGx Blog: https://blog.clinpgx.org/
API documentation: https://api.clinpgx.org/
CPIC website: https://cpicpgx.org/
PharmCAT: https://pharmcat.clinpgx.org/
ClinGen: https://clinicalgenome.org/
Contact: [email protected] (for substantial API use)

clinpgx-database

Preview