OpenFDA_Client

💊 OpenFDA API Client

A Python client for querying adverse events from the FDA Adverse Event Reporting System (FAERS) database.

❓ Why Adverse Event Context?

Drug interaction checking benefits from real-world adverse event data to provide additional safety context:

• How often do patients take these drugs together in practice?
• What adverse reactions are commonly reported with this combination?
• Are there patterns of serious events worth noting?

This complements interaction databases by adding post-market surveillance data that reflects actual patient experiences.

🔄 Input → Processing → Output

📥 Input

Normalized drug ingredient names from RxNorm:

• Generic names: "warfarin", "aspirin"
• Standardized forms: "acetaminophen", "ibuprofen"
• Must be at least 2 drugs for combination analysis

⚙️ Processing

1. Query FAERS database for reports containing all specified drugs
2. PubChem synonym fallback when no reports found
3. Aggregate statistics from matching adverse event reports
4. Extract common reaction patterns and severity indicators
5. Email notifications for failed adverse event lookups
6. Return structured summary for clinical context

🧪 PubChem REST API (Fallback)

• When: Automatic fallback when no FAERS reports found with original drug names
• Process: Retrieves up to 3 synonyms per drug, tests all combinations
• Purpose: Finds adverse event reports using alternative drug names when standardized names don't match FAERS data

For more details about PubChem integration, refer to the PubChem section.

📤 Output JSON

Success (reports found):

{
  "adverse_events": {
    "drugs": ["warfarin", "aspirin"],
    "n_reports": 584860,
    "sample_size": 100
  }
}

No Reports Found:

{
  "drugs": ["drug1", "drug2"],
  "n_reports": 0,
  "reason": "No reports found after synonym search"
}

🚀 Quick Start

from src.clients.openfda import get_adverse_event_context_safe

context = await get_adverse_event_context_safe(ingredient_names)
adverse_events = context["adverse_events"]  # Function returns wrapped dict

if adverse_events['n_reports'] > 0:
    print(f"Found {adverse_events['n_reports']} reports")
    print(f"Common reactions: {adverse_events['top_reactions']}")
else:
    print("No adverse events reported for this combination")

⚠️ Error Handling

Two interfaces available:

• get_adverse_event_context(): Raises OpenFDAError on API failures
• get_adverse_event_context_safe(): Never raises exceptions, returns empty data structure

🔧 Configuration

Default settings:

• 30 second timeout for slow OpenFDA responses
• 3 retries with exponential backoff
• 100 report limit for statistical sampling

🌐 API Usage & Limits

🏥 OpenFDA Drug Adverse Event API

• Provider: U.S. Food and Drug Administration
• Cost: Free
• Rate Limits: About 240 requests/min without API key; higher with key
• Registration: Optional (API key recommended for production use)
• Base URL: https://api.fda.gov/drug/event.json

🗄️ Data Source: FAERS Database

• Coverage: Adverse event reports from 2004-present
• Update Frequency: Quarterly releases
• Data Lag: May lag 3+ months behind current date
• Report Types: Voluntary submissions from healthcare professionals, consumers, and manufacturers

🔍 Search Strategy

Uses patient.drug.medicinalproduct field with AND logic:

patient.drug.medicinalproduct:"warfarin"+patient.drug.medicinalproduct:"aspirin"

⚠️ This finds reports where both drugs were co-reported in the same case. It does not confirm simultaneous administration, only that both appear in the patient’s drug history for the reported event.

🚧 Important Limitations (FAERS / OpenFDA Data)

⚠️ This data provides context, not conclusions. It reflects reported associations between drugs and adverse events, but it cannot prove cause-and-effect, quantify risk, or replace clinical evidence. Use it only as supplementary context for interaction analysis, not primary safety assessment.

• Association ≠ causation

  Example: A patient on aspirin + warfarin has a GI bleed. The report links the drugs and the event, but the bleed might stem from an ulcer or alcohol use.

• Polypharmacy & confounders

  Example: A case listing acetaminophen, aspirin, hydrocodone, and ruxolitinib shows low platelets. It’s impossible to tell which drug—or the underlying disease—was responsible.

• Unclear timing & dosing

  Example: A report lists aspirin and acetaminophen, but doesn’t say if they were taken together or weeks apart.

• No denominator for risk

  Example: 100 liver injury reports for acetaminophen could mean “100 out of millions” (rare) or “100 out of hundreds” (common). The database doesn’t provide exposure numbers.

• Biased & incomplete reporting

  Example: Mild headaches from aspirin rarely get reported, but severe GI bleeds almost always do—skewing the data toward serious outcomes.

🔗 Integration with DrugX Pipeline

# Complete workflow: RxNorm → DDInter → OpenFDA
normalized_drugs = [await normalize_drug_safe(drug) for drug in user_drugs]
ingredient_names = [drug["in"] for drug in normalized_drugs]

# Get interaction data
interactions = await check_drug_interactions(ingredient_names)

# Get adverse event context
adverse_events = await get_adverse_event_context_safe(ingredient_names)