pillfyi

Python API client for pill identification and FDA drug data. Look up medications by imprint code, color, and shape, query the FDA drug database, check drug scheduling (DEA), and retrieve NDC (National Drug Code) details — all from PillFYI, a pill identification platform built on FDA-sourced data.

PillFYI aggregates pill identification data including imprint codes, physical characteristics (color, shape, coating), manufacturer information, and FDA approval status — used by pharmacists, healthcare developers, and patients for reliable medication identification.

Identify pills at pillfyi.com — search by imprint code, color, or shape.

Table of Contents

• Install
• Quick Start
• What You Can Do
  • Pill Identification by Imprint
  • Physical Characteristics Search
  • FDA Drug Database
  • Drug Scheduling (DEA)
• Command-Line Interface
• MCP Server (Claude, Cursor, Windsurf)
• REST API Client
• API Reference
• Learn More About Pills
• Also Available
• Health FYI Family
• License

Install

pip install pillfyi                # Core (zero deps)
pip install "pillfyi[cli]"         # + Command-line interface
pip install "pillfyi[mcp]"         # + MCP server for AI assistants
pip install "pillfyi[api]"         # + HTTP client for pillfyi.com API
pip install "pillfyi[all]"         # Everything

Quick Start

from pillfyi.api import PillFYI

with PillFYI() as api:
    # Identify a pill by its imprint code
    pills = api.search_imprint("M365")
    for pill in pills:
        print(f"{pill['name']} — {pill['color']} {pill['shape']}")

    # Get detailed drug information
    drug = api.get_drug("acetaminophen-hydrocodone")
    print(drug["generic_name"])    # Acetaminophen/Hydrocodone
    print(drug["schedule"])        # Schedule II

    # Browse all pill colors
    colors = api.list_colors()

What You Can Do

Pill Identification by Imprint

Every prescription tablet and capsule in the United States is required by the FDA to have a unique imprint code — a combination of letters, numbers, and symbols debossed or printed on the pill surface. This code, combined with physical characteristics, provides definitive identification.

Imprint Component	Example	Identifies
Letters + Numbers	M365, IP 204	Manufacturer + product code
Logo only	Pfizer "P", Lilly logo	Manufacturer
Numbers only	512, 2172	Product-specific code
Scored line	Single/double score	Tablet divisibility

from pillfyi.api import PillFYI

with PillFYI() as api:
    # Search by imprint code — the most reliable identification method
    results = api.search_imprint("M365")
    for pill in results:
        print(f"{pill['name']}: {pill['color']} {pill['shape']}")
        print(f"  Manufacturer: {pill['manufacturer']}")

Learn more: Pill Imprint Search · Glossary

Physical Characteristics Search

When an imprint is unreadable, pills can be identified by physical characteristics. The FDA Pill Identification database categorizes pills by 12 colors, 10 shapes, and coating type. Combining multiple characteristics narrows results dramatically.

Characteristic	Categories	Examples
Color	12 standard	White, Blue, Yellow, Pink, Orange
Shape	10 standard	Round, Oval, Capsule, Diamond, Pentagon
Coating	3 types	Film-coated, Sugar-coated, Uncoated
Scoring	4 types	Unscored, Single-scored, Double-scored, Triple-scored

from pillfyi.api import PillFYI

with PillFYI() as api:
    # Multi-filter pill identification
    results = api.search(color="white", shape="round")
    print(f"Found {len(results)} matching pills")

    # Browse by color
    colors = api.list_colors()
    for color in colors:
        print(f"{color['name']}: {color['count']} pills")

Learn more: Search by Color · Search by Shape

FDA Drug Database

PillFYI is built on data from the FDA National Drug Code (NDC) Directory and the FDA Pill Identification database. Each drug entry includes the generic name, brand names, manufacturer, active ingredients, dosage forms, and route of administration.

from pillfyi.api import PillFYI

with PillFYI() as api:
    # Look up detailed drug information
    drug = api.get_drug("ibuprofen")
    print(drug["generic_name"])       # Ibuprofen
    print(drug["drug_class"])         # NSAID
    print(drug["dosage_forms"])       # Tablet, Capsule, Suspension
    print(drug["route"])              # Oral

Learn more: Drug Database · Guides

Drug Scheduling (DEA)

The U.S. Drug Enforcement Administration (DEA) classifies controlled substances into five schedules based on their accepted medical use, abuse potential, and safety profile. Schedule I (highest restriction) to Schedule V (lowest restriction).

Schedule	Abuse Potential	Medical Use	Examples
I	High	None accepted	Heroin, LSD, MDMA
II	High	Accepted with restrictions	Oxycodone, Adderall, Fentanyl
III	Moderate	Accepted	Tylenol with Codeine, Ketamine
IV	Low	Accepted	Xanax, Valium, Ambien
V	Lowest	Accepted	Robitussin AC, Lyrica

from pillfyi.api import PillFYI

with PillFYI() as api:
    # Check drug scheduling
    drug = api.get_drug("oxycodone")
    print(drug["schedule"])        # Schedule II
    print(drug["controlled"])      # True

Learn more: Drug Schedules · Glossary

Command-Line Interface

pip install "pillfyi[cli]"

pillfyi imprint M365                   # Identify pill by imprint
pillfyi search --color white --shape round  # Physical characteristics
pillfyi drug ibuprofen                 # Drug details
pillfyi colors                         # List all pill colors
pillfyi shapes                         # List all pill shapes

MCP Server (Claude, Cursor, Windsurf)

pip install "pillfyi[mcp]"

{
    "mcpServers": {
        "pillfyi": {
            "command": "uvx",
            "args": ["--from", "pillfyi[mcp]", "python", "-m", "pillfyi.mcp_server"]
        }
    }
}

REST API Client

from pillfyi.api import PillFYI

with PillFYI() as api:
    pills = api.search_imprint("M365")         # GET /api/v1/pills/?imprint=M365
    drug = api.get_drug("ibuprofen")            # GET /api/v1/drugs/ibuprofen/
    colors = api.list_colors()                  # GET /api/v1/colors/
    results = api.search(color="blue")          # GET /api/v1/search/?color=blue

Example

curl -s "https://pillfyi.com/api/v1/drugs/ibuprofen/"

{
    "slug": "ibuprofen",
    "generic_name": "Ibuprofen",
    "drug_class": "NSAID",
    "dosage_forms": ["Tablet", "Capsule", "Suspension"],
    "route": "Oral"
}

Full API documentation at pillfyi.com/developers/.

API Reference

Function	Description
api.search_imprint(code)	Identify pills by imprint code
api.search(color, shape)	Search by physical characteristics
api.get_drug(slug)	Detailed drug information
api.list_drugs()	List all drugs in database
api.list_colors()	All pill color categories
api.list_shapes()	All pill shape categories

Learn More About Pills

• Browse: Pill Imprints · Colors · Shapes
• Guides: Pill Identification Guides · Glossary
• API: REST API Docs · OpenAPI Spec

Also Available

Platform	Install	Link
npm	npm install pillfyi	npm
MCP	uvx --from "pillfyi[mcp]" python -m pillfyi.mcp_server	Config

Health FYI Family

Part of the FYIPedia open-source developer tools ecosystem — human body, medicine, and nutrition.

Package	PyPI	npm	Description
anatomyfyi	PyPI	npm	14,692 anatomical structures, body systems, organs — anatomyfyi.com
pillfyi	PyPI	npm	Pill identification, FDA drug database — pillfyi.com
drugfyi	PyPI	npm	Drug interactions, pharmacology, side effects — drugfyi.com
nutrifyi	PyPI	npm	Nutrition data, food composition, dietary analysis — nutrifyi.com

License

MIT