# pillfyi

[![PyPI version](https://agentgif.com/badge/pypi/pillfyi/version.svg)](https://pypi.org/project/pillfyi/)
[![Python](https://img.shields.io/pypi/pyversions/pillfyi)](https://pypi.org/project/pillfyi/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](https://pypi.org/project/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](https://pillfyi.com/), 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](https://pillfyi.com/)** — search by [imprint code](https://pillfyi.com/imprints/), [color](https://pillfyi.com/colors/), or [shape](https://pillfyi.com/shapes/).

<p align="center">
  <img src="https://raw.githubusercontent.com/fyipedia/pillfyi/main/demo.gif" alt="pillfyi demo — pill identification, FDA drug lookup, and imprint search in Python" width="800">
</p>

## Table of Contents

- [Install](#install)
- [Quick Start](#quick-start)
- [What You Can Do](#what-you-can-do)
  - [Pill Identification by Imprint](#pill-identification-by-imprint)
  - [Physical Characteristics Search](#physical-characteristics-search)
  - [FDA Drug Database](#fda-drug-database)
  - [Drug Scheduling (DEA)](#drug-scheduling-dea)
- [Command-Line Interface](#command-line-interface)
- [MCP Server (Claude, Cursor, Windsurf)](#mcp-server-claude-cursor-windsurf)
- [REST API Client](#rest-api-client)
- [API Reference](#api-reference)
- [Learn More About Pills](#learn-more-about-pills)
- [Also Available](#also-available)
- [Health FYI Family](#health-fyi-family)
- [License](#license)

## Install

```bash
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

```python
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 |

```python
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](https://pillfyi.com/imprints/) · [Glossary](https://pillfyi.com/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 |

```python
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](https://pillfyi.com/colors/) · [Search by Shape](https://pillfyi.com/shapes/)

### 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.

```python
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](https://pillfyi.com/drugs/) · [Guides](https://pillfyi.com/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 |

```python
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](https://pillfyi.com/guides/) · [Glossary](https://pillfyi.com/glossary/)

## Command-Line Interface

```bash
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)

```bash
pip install "pillfyi[mcp]"
```

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

## REST API Client

```python
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

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

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

Full API documentation at [pillfyi.com/developers/](https://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](https://pillfyi.com/imprints/) · [Colors](https://pillfyi.com/colors/) · [Shapes](https://pillfyi.com/shapes/)
- **Guides**: [Pill Identification Guides](https://pillfyi.com/guides/) · [Glossary](https://pillfyi.com/glossary/)
- **API**: [REST API Docs](https://pillfyi.com/developers/) · [OpenAPI Spec](https://pillfyi.com/api/openapi.json)

## Also Available

| Platform | Install | Link |
|----------|---------|------|
| **npm** | `npm install pillfyi` | [npm](https://www.npmjs.com/package/pillfyi) |
| **MCP** | `uvx --from "pillfyi[mcp]" python -m pillfyi.mcp_server` | [Config](#mcp-server-claude-cursor-windsurf) |

## Health FYI Family

Part of the [FYIPedia](https://fyipedia.com) open-source developer tools ecosystem — human body, medicine, and nutrition.

| Package | PyPI | npm | Description |
|---------|------|-----|-------------|
| anatomyfyi | [PyPI](https://pypi.org/project/anatomyfyi/) | [npm](https://www.npmjs.com/package/anatomyfyi) | 14,692 anatomical structures, body systems, organs — [anatomyfyi.com](https://anatomyfyi.com/) |
| **pillfyi** | [PyPI](https://pypi.org/project/pillfyi/) | [npm](https://www.npmjs.com/package/pillfyi) | **Pill identification, FDA drug database — [pillfyi.com](https://pillfyi.com/)** |
| drugfyi | [PyPI](https://pypi.org/project/drugfyi/) | [npm](https://www.npmjs.com/package/drugfyi) | Drug interactions, pharmacology, side effects — [drugfyi.com](https://drugfyi.com/) |
| nutrifyi | [PyPI](https://pypi.org/project/nutrifyi/) | [npm](https://www.npmjs.com/package/nutrifyi) | Nutrition data, food composition, dietary analysis — [nutrifyi.com](https://nutrifyi.com/) |

## License

MIT
