openfda-database
Query, search, and download data from the openFDA API for drugs, devices, foods, tobacco, cosmetics, animal and veterinary products, substances, and transparency data.
Install / Use
npx skills add google-deepmind/science-skills --skill openfda_databaseInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Data & AnalyticsSupported Platforms
Our assessment of openfda-database
openfda-database scores 93/100 on our quality scale, 119th of 604 Data & Analytics skills we index (top 20%).
Its SKILL.md is 9.7 KB long, well organised into 21 sections with 7 code examples: a thorough specification that gives an agent plenty to work with.
With 3,137 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 2 months ago, so openfda-database is actively maintained.
- Our last check on 2026-10-26 found the source still online.
- It is released under the Apache-2.0 license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-09-29. Automated pattern scan on 2026-09-29. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
openfda-database compared with similar skills
All 4 of these similar skills score higher than openfda-database; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| openfda-database (this skill)by google-deepmind | 93 | 3.1k | 2mo ago | SKILL.md |
| Agent-Reachby Panniantong | 100 | 112.3k | 8d ago | CLAUDE.md |
| headroomby headroomlabs-ai | 100 | 79.8k | today | CLAUDE.md |
| Scraplingby D4Vinci | 100 | 103.6k | 2d ago | MCP Server |
| crawl4aiby unclecode | 100 | 87.4k | 3d ago | MCP Server |
Frequently asked questions
- How do I install openfda-database?
- Run
npx skills add google-deepmind/science-skills --skill openfda-database. The install tabs above show the steps for each supported agent. - Which AI agents does openfda-database work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is openfda-database safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is Apache-2.0-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is openfda-database still maintained?
- The repository was last updated about 2 months ago, so openfda-database is actively maintained.
Skill content
View source on GitHubname: openfda-database description: > Query, search, and download data from the openFDA API for drugs, devices, foods, tobacco, cosmetics, animal and veterinary products, substances, and transparency data. Use for FDA adverse events, recalls, labeling, approvals, shortages, 510(k) clearances, NDC lookups, and any FDA safety or regulatory data query across all 28 API endpoints.
openFDA Search and Query
Prerequisites
uv: Read theuvskill and follow its Setup instructions to ensureuvis installed and on PATH.- User Notification: If .licenses/openfda_database_LICENSE.txt does not already exist in the workspace root directory then (1) prominently notify the user to check the terms at https://open.fda.gov/apis/ and https://open.fda.gov/license, then (2) create the file recording the notification text and timestamp.
.envfile: Make sure the.envfile exists in your home directory. Create one if it does not exist.FDA_API_KEY(optional but recommended): Raises the daily request limit from 1,000 to 120,000. The skill works without it, but an agent can easily exhaust the keyless limit in a single session. You can register for a free key at https://open.fda.gov/apis/authentication/. You MUST use the safe credentials protocol in thecredentialsskill to check for and request this key if this skill looks relevant to the user's request.
Core Rules
-
Use the Wrapper: ALWAYS execute the provided helper scripts to query the database rather than accessing the database directly. The scripts automatically enforce the required rate limit gracefully.
-
Rate Limiting: Respect openFDA rate limits. Without API key: 240 requests/min, 1,000 requests/day per IP. With API key: 240 requests/min, 120,000 requests/day per key. Always set an API key before running multi-query workflows.
Warning: An automated agent can easily exhaust the 1,000-request daily limit in a single research session. Always set an API key before running multi-query workflows.
You MUST use the safe credentials protocol in the
credentialsskill to help the user addFDA_API_KEYto their.envfile if this skill looks relevant to the user's request. The script will emit a warning to stderr if no API key is detected.
-
Always Use
--output: All subcommands require--output <file>to write results to a file. This prevents large output becoming overwhelming. Use jq or code to read the output file. -
Notification: If this skill is used, ensure this is mentioned in the output.
Utility Script
Single script for all operations:
uv run scripts/openfda_query.py {search,count,download} --output <file> [options]
1. Search
Search any of the 28 endpoints and save JSON results to a file.
uv run scripts/openfda_query.py search \
--category drug --endpoint event \
--search "patient.drug.medicinalproduct:aspirin" \
--limit 5 --output /tmp/fda_results.json
Stdout prints a compact summary:
{"status": "success", "output": "/tmp/fda_results.json", "results_in_file": 5, "total_matching": 601477}
Options:
--output: Output file for full JSON results (required).--category: API category —drug,device,food,tobacco,other,animalandveterinary,cosmetic,transparency.--endpoint: Endpoint within the category (e.g.,event,label,510k). See references/api_endpoints.md for full list.--search: Query string (e.g.,patient.drug.medicinalproduct:aspirin+AND+serious:1).--sort: Sort field and order (e.g.,receivedate:desc).--limit: Max results (default 10, max 1000).--skip: Pagination offset (default 0).--api_key: API key (also readsFDA_API_KEYenv var).
2. Count
Count unique values of a field within matching results.
uv run scripts/openfda_query.py count \
--category drug --endpoint event \
--search "patient.drug.medicinalproduct:aspirin" \
--count_field "patient.reaction.reactionmeddrapt.exact" \
--summary 10 --output /tmp/aspirin_reactions.json
Stdout prints a summary with the top 5 terms. Full data is in the output file.
Additional options:
--count_field: Field to count (append.exactfor whole-phrase counting).--summary N: Return only the top N most frequent terms. Use this to avoid flooding the context with hundreds of infrequent terms.
3. Download
Download multiple pages of results to a file.
uv run scripts/openfda_query.py download \
--category drug --endpoint event \
--search "patient.drug.medicinalproduct:aspirin" \
--limit 100 --max_pages 5 \
--output /tmp/aspirin_events.json
Additional options:
-
--max_pages: Maximum pages to fetch (default 10). -
--all_results: Automatically paginate to fetch all matching results. Safety cap of 25,000 records maximum per download to prevent runaway downloads and prevent excessive API usage.Tip: Common drugs can have excessive reports. Use a date range (e.g.,
receivedate:[20250101+TO+20250131]) to limit the volume of download.
Entity Resolution: Using .exact for Precision
When searching for specific product names, drug names, or categorical terms,
always use the .exact suffix on the field to get exact-match results. Without
it, the API tokenizes multi-word values and returns noisy partial matches.
# Precise: matches only "ADVIL"
uv run scripts/openfda_query.py search --category drug --endpoint label \
--search 'openfda.brand_name.exact:"ADVIL"' \
--limit 5 --output /tmp/advil_label.json
Note: Many brand names in the FDA database include variant suffixes (e.g., "TYLENOL Extra Strength" rather than just "TYLENOL"). If an
.exactsearch returns 0 results, try without.exactto see the available brand name variants, then re-query with the full exact name.
The .exact suffix is also required when using --count_field to aggregate
whole phrases instead of individual words.
NDC Lookups: Hyphens & Discontinued Drugs
-
Always Quote Hyphenated NDCs: In openFDA search syntax, an unquoted hyphen (
-) acts as the boolean NOT operator (e.g.,51285-092searches for51285 AND NOT 092). Always enclose hyphenated NDC strings in escaped double quotes:uv run scripts/openfda_query.py search --category drug --endpoint ndc \ --search 'product_ndc:"51285-092"' \ --limit 5 --output /tmp/ndc.json -
Discontinued Drugs Fallback (
drug/label): Thedrug/ndcendpoint only contains currently active/marketed products. If a valid NDC returns 0 results indrug/ndc, query thedrug/labelendpoint with exact phrase quotes (--search '"51285-092"'). Note that for discontinued drugs, theopenfdametadata block may be empty ({}), so read brand name, active ingredients, and labeler from the label text fields (package_label_principal_display_panel,description, orspl_product_data_elements).
MedDRA Term Resolution
openFDA adverse event data uses MedDRA (Medical Dictionary for Regulatory Activities) terms for reactions. The API reports Preferred Terms (PTs) but does not provide the MedDRA hierarchy (System Organ Class, High Level Terms, etc.).
Note: MedDRA is a proprietary ontology and is not indexed in the EMBL-EBI OLS. To approximate MedDRA hierarchy lookups, use the Human Phenotype Ontology (HP) or NCI Thesaurus (NCIT) as proxy ontologies — they cross-reference MedDRA IDs and provide parent/ancestor relationships.
# Step 1: Get top reactions from openFDA
uv run scripts/openfda_query.py count \
--category drug --endpoint event \
--search "patient.drug.medicinalproduct:metformin" \
--count_field "patient.reaction.reactionmeddrapt.exact" \
--summary 5 --output /tmp/metformin_reactions.json
# Step 2: Look up the top reaction term using a biomedical ontology service
# skill (e.g. embl-ebi-ols skill).
# MedDRA is not available in OLS; use the Human Phenotype Ontology (HP) or
# NCI Thesaurus (NCIT) as a proxy to find the hierarchical classification of
# the reaction term.
Available Endpoints (28 total)
Category to endpoint mapping:
drug: event, label, ndc, enforcement, drugsfda, shortagesdevice: 510k, classification, enforcement, event, pma, recall, registrationlisting, udi, covid19serologyfood: enforcement, eventtobacco: problem, researchpreventionads, researchdigitalads, researchsmokefreeother: historicaldocument, nsde, substance, uniianimalandveterinary: eventcosmetic: eventtransparency: crl
Reference
- Query syntax and all endpoints: See references/api_endpoints.md for field names, search syntax, date ranges, and boolean operators.
Recipes
Common query patterns for drugs, devices, foods, tobacco, cosmetics, animal and veterinary products, substances, transparency data, adverse events, recalls, labeling, approvals, shortages, 510(k) clearances, NDC lookups, any FDA safety or regulatory data query, and more. See references/recipes.md for the full recipes.
Workflow
- Search for records using
searchwith--output. Read the output file. - Use
countwith--summary 10 --outputto summarize field distributions. - Use
download(with--all_resultsfor exhaustive pulls) to fetch larger datasets. - Read and analyze the output file using standard tools.
- For MedDRA term hierarchy questions, use a biomedical ontology service skill (e.g. EMBL-EBI OLS skill with the HP or NCIT ontology) to look up the term.
Related Skills
Agent-Reach
112.3kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
headroom
79.8kCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Scrapling
103.6k🕷️ The BEST Web Scraping framework that handles everything from a single request to a full-scale crawl! Don't be shy, join here: https://discord.gg/EMgGbDceNQ and follow here for daily tips and tricks: https://x.com/Scrapling_dev
crawl4ai
87.4kOfficial Crawl4AI Cloud: a hosted web scraping, extraction, and search API for AI agents. Free API key, 1,000 credits a month, no card. Fully open source: this repo is the Apache-2.0 crawler that powers it, and you can self-host it.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
