fda-database

Access comprehensive FDA regulatory data through openFDA, the FDA's initiative to provide open APIs for public datasets. Query information about drugs, medical devices, foods, animal/veterinary products, and substances using Python with standardized interfaces.

Key capabilities:

• Query adverse events for drugs, devices, foods, and veterinary products
• Access product labeling, approvals, and regulatory submissions
• Monitor recalls and enforcement actions
• Look up National Drug Codes (NDC) and substance identifiers (UNII)
• Analyze device classifications and clearances (510k, PMA)
• Track drug shortages and supply issues
• Research chemical structures and substance relationships

This skill should be used when working with:

• Drug research: Safety profiles, adverse events, labeling, approvals, shortages
• Medical device surveillance: Adverse events, recalls, 510(k) clearances, PMA approvals
• Food safety: Recalls, allergen tracking, adverse events, dietary supplements
• Veterinary medicine: Animal drug adverse events by species and breed
• Chemical/substance data: UNII lookup, CAS number mapping, molecular structures
• Regulatory analysis: Approval pathways, enforcement actions, compliance tracking
• Pharmacovigilance: Post-market surveillance, safety signal detection
• Scientific research: Drug interactions, comparative safety, epidemiological studies

1. Basic Setup

```python

from scripts.fda_query import FDAQuery

# Initialize (API key optional but recommended)

fda = FDAQuery(api_key="YOUR_API_KEY")

# Query drug adverse events

events = fda.query_drug_events("aspirin", limit=100)

# Get drug labeling

label = fda.query_drug_label("Lipitor", brand=True)

# Search device recalls

recalls = fda.query("device", "enforcement",

search="classification:Class+I",

limit=50)

```

2. API Key Setup

While the API works without a key, registering provides higher rate limits:

• Without key: 240 requests/min, 1,000/day
• With key: 240 requests/min, 120,000/day

Register at: https://open.fda.gov/apis/authentication/

Set as environment variable:

```bash

export FDA_API_KEY="your_key_here"

```

3. Running Examples

```bash

# Run comprehensive examples

python scripts/fda_examples.py

# This demonstrates:

# - Drug safety profiles

# - Device surveillance

# - Food recall monitoring

# - Substance lookup

# - Comparative drug analysis

# - Veterinary drug analysis

```

Drugs

Access 6 drug-related endpoints covering the full drug lifecycle from approval to post-market surveillance.

Endpoints:

1. Adverse Events - Reports of side effects, errors, and therapeutic failures
2. Product Labeling - Prescribing information, warnings, indications
3. NDC Directory - National Drug Code product information
4. Enforcement Reports - Drug recalls and safety actions
5. Drugs@FDA - Historical approval data since 1939
6. Drug Shortages - Current and resolved supply issues

Common use cases:

```python

# Safety signal detection

fda.count_by_field("drug", "event",

search="patient.drug.medicinalproduct:metformin",

field="patient.reaction.reactionmeddrapt")

# Get prescribing information

label = fda.query_drug_label("Keytruda", brand=True)

# Check for recalls

recalls = fda.query_drug_recalls(drug_name="metformin")

# Monitor shortages

shortages = fda.query("drug", "drugshortages",

search="status:Currently+in+Shortage")

```

Reference: See references/drugs.md for detailed documentation

Devices

Access 9 device-related endpoints covering medical device safety, approvals, and registrations.

Endpoints:

1. Adverse Events - Device malfunctions, injuries, deaths
2. 510(k) Clearances - Premarket notifications
3. Classification - Device categories and risk classes
4. Enforcement Reports - Device recalls
5. Recalls - Detailed recall information
6. PMA - Premarket approval data for Class III devices
7. Registrations & Listings - Manufacturing facility data
8. UDI - Unique Device Identification database
9. COVID-19 Serology - Antibody test performance data

Common use cases:

```python

# Monitor device safety

events = fda.query_device_events("pacemaker", limit=100)

# Look up device classification

classification = fda.query_device_classification("DQY")

# Find 510(k) clearances

clearances = fda.query_device_510k(applicant="Medtronic")

# Search by UDI

device_info = fda.query("device", "udi",

search="identifiers.id:00884838003019")

```

Reference: See references/devices.md for detailed documentation

Foods

Access 2 food-related endpoints for safety monitoring and recalls.

Endpoints:

1. Adverse Events - Food, dietary supplement, and cosmetic events
2. Enforcement Reports - Food product recalls

Common use cases:

```python

# Monitor allergen recalls

recalls = fda.query_food_recalls(reason="undeclared peanut")

# Track dietary supplement events

events = fda.query_food_events(

industry="Dietary Supplements")

# Find contamination recalls

listeria = fda.query_food_recalls(

reason="listeria",

classification="I")

```

Reference: See references/foods.md for detailed documentation

Animal & Veterinary

Access veterinary drug adverse event data with species-specific information.

Endpoint:

1. Adverse Events - Animal drug side effects by species, breed, and product

Common use cases:

```python

# Species-specific events

dog_events = fda.query_animal_events(

species="Dog",

drug_name="flea collar")

# Breed predisposition analysis

breed_query = fda.query("animalandveterinary", "event",

search="reaction.veddra_term_name:seizure+AND+"

"animal.breed.breed_component:Labrador")

```

Reference: See references/animal_veterinary.md for detailed documentation

Substances & Other

Access molecular-level substance data with UNII codes, chemical structures, and relationships.

Endpoints:

1. Substance Data - UNII, CAS, chemical structures, relationships
2. NSDE - Historical substance data (legacy)

Common use cases:

```python

# UNII to CAS mapping

substance = fda.query_substance_by_unii("R16CO5Y76E")

# Search by name

results = fda.query_substance_by_name("acetaminophen")

# Get chemical structure

structure = fda.query("other", "substance",

search="names.name:ibuprofen+AND+substanceClass:chemical")

```

Reference: See references/other.md for detailed documentation

Pattern 1: Safety Profile Analysis

Create comprehensive safety profiles combining multiple data sources:

```python

def drug_safety_profile(fda, drug_name):

"""Generate complete safety profile."""

# 1. Total adverse events

events = fda.query_drug_events(drug_name, limit=1)

total = events["meta"]["results"]["total"]

# 2. Most common reactions

reactions = fda.count_by_field(

"drug", "event",

search=f"patient.drug.medicinalproduct:{drug_name}",

field="patient.reaction.reactionmeddrapt",

exact=True

)

# 3. Serious events

serious = fda.query("drug", "event",

search=f"patient.drug.medicinalproduct:{drug_name}+AND+serious:1",

limit=1)

# 4. Recent recalls

recalls = fda.query_drug_recalls(drug_name=drug_name)

return {

"total_events": total,

"top_reactions": reactions["results"][:10],

"serious_events": serious["meta"]["results"]["total"],

"recalls": recalls["results"]

}

```

Pattern 2: Temporal Trend Analysis

Analyze trends over time using date ranges:

```python

from datetime import datetime, timedelta

def get_monthly_trends(fda, drug_name, months=12):

"""Get monthly adverse event trends."""

trends = []

for i in range(months):

end = datetime.now() - timedelta(days=30*i)

start = end - timedelta(days=30)

date_range = f"[{start.strftime('%Y%m%d')}+TO+{end.strftime('%Y%m%d')}]"

search = f"patient.drug.medicinalproduct:{drug_name}+AND+receivedate:{date_range}"

result = fda.query("drug", "event", search=search, limit=1)

count = result["meta"]["results"]["total"] if "meta" in result else 0

trends.append({

"month": start.strftime("%Y-%m"),

"events": count

})

return trends

```

Pattern 3: Comparative Analysis

Compare multiple products side-by-side:

```python

def compare_drugs(fda, drug_list):

"""Compare safety profiles of multiple drugs."""

comparison = {}

for drug in drug_list:

# Total events

events = fda.query_drug_events(drug, limit=1)

total = events["meta"]["results"]["total"] if "meta" in events else 0

# Serious events

serious = fda.query("drug", "event",

search=f"patient.drug.medicinalproduct:{drug}+AND+serious:1",

limit=1)

serious_count = serious["meta"]["results"]["total"] if "meta" in serious else 0

comparison[drug] = {

"total_events": total,

"serious_events": serious_count,

"serious_rate": (serious_count/total*100) if total > 0 else 0

}

return comparison

```

Pattern 4: Cross-Database Lookup

Link data across multiple endpoints:

```python

def comprehensive_device_lookup(fda, device_name):

"""Look up device across all relevant databases."""

return {

"adverse_events": fda.query_device_events(device_name, limit=10),

"510k_clearances": fda.query_device_510k(device_name=device_name),

"recalls": fda.query("device", "enforcement",

search=f"product_description:{device_name}"),

"udi_info": fda.query("device", "udi",

search=f"brand_name:{device_name}")

}

```

Response Structure

All API responses follow this structure:

```python

{

"meta": {

"disclaimer": "...",

"results": {

"skip": 0,

"limit": 100,

"total": 15234

}

},

"results": [

# Array of result objects

]

}

```

Error Handling

Always handle potential errors:

```python

result = fda.query_drug_events("aspirin", limit=10)

if "error" in result:

print(f"Error: {result['error']}")

elif "results" not in result or len(result["results"]) == 0:

print("No results found")

else:

# Process results

for event in result["results"]:

# Handle event data

pass

```

Pagination

For large result sets, use pagination:

```python

# Automatic pagination

all_results = fda.query_all(

"drug", "event",

search="patient.drug.medicinalproduct:aspirin",

max_results=5000

)

# Manual pagination

for skip in range(0, 1000, 100):

batch = fda.query("drug", "event",

search="...",

limit=100,

skip=skip)

# Process batch

```

1. Use Specific Searches

DO:

```python

# Specific field search

search="patient.drug.medicinalproduct:aspirin"

```

DON'T:

```python

# Overly broad wildcard

search="aspirin"

```

2. Implement Rate Limiting

The FDAQuery class handles rate limiting automatically, but be aware of limits:

• 240 requests per minute
• 120,000 requests per day (with API key)

3. Cache Frequently Accessed Data

The FDAQuery class includes built-in caching (enabled by default):

```python

# Caching is automatic

fda = FDAQuery(api_key=api_key, use_cache=True, cache_ttl=3600)

```

4. Use Exact Matching for Counting

When counting/aggregating, use .exact suffix:

```python

# Count exact phrases

fda.count_by_field("drug", "event",

search="...",

field="patient.reaction.reactionmeddrapt",

exact=True) # Adds .exact automatically

```

5. Validate Input Data

Clean and validate search terms:

```python

def clean_drug_name(name):

"""Clean drug name for query."""

return name.strip().replace('"', '\\"')

drug_name = clean_drug_name(user_input)

```

For detailed information about:

• Authentication and rate limits → See references/api_basics.md
• Drug databases → See references/drugs.md
• Device databases → See references/devices.md
• Food databases → See references/foods.md
• Animal/veterinary databases → See references/animal_veterinary.md
• Substance databases → See references/other.md

`scripts/fda_query.py`

Main query module with FDAQuery class providing:

• Unified interface to all FDA endpoints
• Automatic rate limiting and caching
• Error handling and retry logic
• Common query patterns

`scripts/fda_examples.py`

Comprehensive examples demonstrating:

• Drug safety profile analysis
• Device surveillance monitoring
• Food recall tracking
• Substance lookup
• Comparative drug analysis
• Veterinary drug analysis

Run examples:

```bash

python scripts/fda_examples.py

```

• openFDA Homepage: https://open.fda.gov/
• API Documentation: https://open.fda.gov/apis/
• Interactive API Explorer: https://open.fda.gov/apis/try-the-api/
• GitHub Repository: https://github.com/FDA/openfda
• Terms of Service: https://open.fda.gov/terms/

Common Issues

Issue: Rate limit exceeded

• Solution: Use API key, implement delays, or reduce request frequency

Issue: No results found

• Solution: Try broader search terms, check spelling, use wildcards

Issue: Invalid query syntax

• Solution: Review query syntax in references/api_basics.md

Issue: Missing fields in results

• Solution: Not all records contain all fields; always check field existence

Getting Help

• GitHub Issues: https://github.com/FDA/openfda/issues
• Email: open-fda@fda.hhs.gov