-
Notifications
You must be signed in to change notification settings - Fork 15
Pillbox API documentation
Pillbox is a resource of the U.S. National Library of Medicine, part of the National Institutes of Health, U.S. Department of Health and Human Services.
The Pillbox API identifies unknown pills based on how they look, their ingredients, and a few other criteria. It also answers questions like “What pills contain acetaminophen?” or “What pills contain lactose as an inactive ingredient?” Pillbox will also tell you the RXCUI or product code for a pill or tell you what the pill is if you have either of those numbers.
The REST API returns XML for all pills that match the search parameters. For each of those possible matches, the API provides detailed information about the look of the pill, it’s ingredients, and information that can be used to link to the drug label or other pharmacy information resources. Additionally images of pills are also returned. This feature is currently limited to a small number of records (see Known limitations).
All calls require an API key. Keys are available at http://pillbox.nlm.nih.gov/signup.html
Pillbox’s data is created by combining drug information resources from the Food and Drug Administration (FDA) and National Library of Medicine (NLM) at the National Institutes of Health. This information has been reformatted to make it easier to work with but has not been verified by FDA or NLM. The information available through this API may not be the labeling on currently distributed products or identical to the labeling that is approved. NLM makes no warranty that the data is error free. See http://pillbox.nlm.nih.gov/API-documentation.html for further information.
Pillbox currently contains 2,159 pill images. While all of images provided by Pillbox were created through a National Library of Medicine/Food and Drug Administration partnership, most are not yet part of the FDA Structured Product Labels (drug labels) and have not yet been verified by the manufacturer/labeler.
Physical appearance data (imprint, color, shape, size, score) for records which have an image have been checked against that images. In cases where the physical characteristics data has been found to be in error, data have been changed to the correct value. A table of changes made is available at Pillbox.
Use of this API is subject to the Disclaimer and Terms of Service displayed on the Pillbox API/Data page.
1. Base URL
2. Example API calls
3. Sample output
4. Parameters
5. Parameter definitions
6. Schema dictionary
7. Image URIs
8. Known limitations
9. Planned API/data upgrades
http://pillbox.nlm.nih.gov/PHP/pillboxAPIService.php
Search for round, white pills containing “aspirin” as an ingredient.
security key = 12345 (inactive key)
FDA coding for round = C48348
FDA coding for white = C48325
http://pillbox.nlm.nih.gov/PHP/pillboxAPIService.php?key=12345&shape=C48348&color=C48325&ingredient=aspirin
Search for pill with FDA Product Code 0078-0176
http://pillbox.nlm.nih.gov/PHP/pillboxAPIService.php?prodcode=0078-0176&key=12345
<?xml version=“1.0” encoding=“UTF-8” ?>
<Pills>
<disclaimer>Most images available via Pillbox are not yet part of the official drug labeling and have not yet been verified by the manufacturer/labeler. Data may be different from that submitted by the labeler. NLM makes no warranty that the data is error free. See http://pillbox.nlm.nih.gov/API-documentation.html for further information.</disclaimer>
<pill>
<SPL_ID>1845</SPL_ID>
<PRODUCT_CODE>0089-0231</PRODUCT_CODE>
<NDC9>000890231</NDC9>
<SPLCOLOR>C48325</SPLCOLOR>
<SPLIMPRINT>NORGESIC;3M</SPLIMPRINT>
<SPLSHAPE>C48348</SPLSHAPE>
<SPLSIZE>11.00</SPLSIZE>
<SPLSCORE>1</SPLSCORE>
<RXCUI>211468</RXCUI>
<RXTTY>SBD</RXTTY>
<RXSTRING>Aspirin 385 MG / Caffeine 30 MG / Orphenadrine 25 MG Oral Tablet [Norgesic]</RXSTRING>
<INGREDIENTS>Aspirin; Caffeine; Orphenadrine</INGREDIENTS>
<HAS_IMAGE>0</HAS_IMAGE>
<image_id></image_id>
<SETID>a7fa86b5-2154-4b17-9265-8a5411c88d5d</SETID>
</pill>
…
</Pills>
Text in brackets indicates the corresponding field in the Pillbox data schema returned by the API.
Input/Output
author – drug label author [author]
color – FDA SPL code for color of pill (see definition below) [SPLCOLOR]
dea – DEA Schedule [DEA_SCHEDULE_CODE]
has_image – search for records with or without pill images [HAS_IMAGE]
imprint – text appearing on the pill [SPLIMPRINT]
inactive – name of an inactive ingredient [SPL_INACTIVE_ING]
ingredient – name of an active ingredient. Currently only one ingredient may be searched in each call. There is currently no spellchecker. INGREDIENTS and [RXSTRING]
key – security key required for API access
lower_limit – starting record for paginated results (must be <=201)
prodcode – FDA 9-digit Product Code in dashed format [PRODUCT_CODE]
rxcui – RxNorm Concept Unique Identifier (RXCUI) [RXCUI]
score – numeric value for FDA score value for pill [SPLSCORE]
shape – FDA SPL code for shape of pill (see definition below) [SPLSHAPE]
size – numeric value (whole number) for size in mm of pill. Search +/- 2 mm [SPLSIZE]
The following fields are returned by the API but are not searchable parameters.
image_id – identification number of the pill image, if one exists [image_id]
NDC9 – Product code in 9-digit format [NDC9]
RXTTY – RxNorm term type [RXTTY]
SETID – reference number for a product’s drug label, downloadable via DailyMed [SETID]
SPL_ID – legacy field which will soon be depricated [SPL_ID]
Text in brackets indicate the fields in the Pillbox data schema searched by each parameter.
Searches for a specific drug label author (company).
FDA form and submission requirements for color.
An xml file containing the FDA SPL codes and values for color is included in the FDA Terminology Validation Files.
FDA SPL codes for color.
BLACK C48323
BLUE C48333
BROWN C48332
GRAY C48324
GREEN C48329
ORANGE C48331
PINK C48328
PURPLE C48327
RED C48326
TURQUOISE C48334
WHITE C48325
YELLOW C48330
[from US Department of Justice]
Drugs and other substances that are considered controlled substances under the Controlled Substances Act (CSA) are divided into five schedules. An updated and complete list of the schedules is published annually in Title 21 Code of Federal Regulations (C.F.R.) §§ 1308.11 through 1308.15. Substances are placed in their respective schedules based on whether they have a currently accepted medical use in treatment in the United States, their relative abuse potential, and likelihood of causing dependence when abused. Some examples of the drugs in each schedule are listed below.
FDA form and submission requirements for DEA schedule.
An xml file containing the FDA SPL codes and values for DEA schedule is included in the FDA Terminology Validation Files.
CI Schedule I C48672
CII Schedule II C48675
CIII Schedule III C48676
CIV Schedule IV C48677
CV Schedule V C48679
not scheduled NULL
Constrain search results to records which either have (has_image = 1) or do not have (has_image is NULL) pill images.
Spaces should be formatted as %20
FDA form and submission requirements for imprint.
The API returns a maximum of 200 results, regardless of the total number of results indicates. lower_limit specifies a starting record for paginated results. It’s value must be greater than or equal to 201. Developers who want the full data set may download it at [LINK].
RxNorm term type.
SBD – Semantic Branded Dose terms use the branding information [NEEDS BETTER DEFINITION]
SCD – Semantic Clinical Dose terms use the ingredient information [NEEDS BETTER DEFINITION]
SY – [NEEDS DEFINITION]
records with no RXTTY are NULL
FDA form and submission requirements for score.
[from above link]
Description: A characteristic of an oral solid dosage form of a medicinal product, specifying the number of equal pieces that the solid dosage form can be divided into using score line(s).
Example: One score line creating two equal pieces is given a value of 2, two parallel score lines creating three equal pieces is given a value of 3.
Constraints: Whether three parallel score lines create four equal pieces or two intersecting score lines create two equal pieces using one score line and four equal pieces using both score lines, both have the scoring value of 4. Solid dosage forms that are not scored are given a value of 1. Solid dosage forms that can only be divided into unequal pieces are given a null-value with nullFlavor other (OTH).
shape [SPLSHAPE]
FDA form and submission requirements for shape.
An xml file containing the FDA SPL codes and values for shape is included in the FDA Terminology Validation Files.
FDA SPL codes for shape.
BULLET C48335
CAPSULE C48336
CLOVER C48337
DIAMOND C48338
DOUBLE CIRCLE C48339
FREEFORM C48340
GEAR C48341
HEPTAGON (7 sided) C48342
HEXAGON (6 sided) C48343
OCTAGON (8 sided) C48344
OVAL C48345
PENTAGON (5 sided) C48346
RECTANGLE C48347
ROUND C48348
SEMI-CIRCLE C48349
SQUARE C48350
TEAR C48351
TRAPEZOID C48352
TRIANGLE C48353
size [SPLSIZE]
FDA form and submission requirements for size.
[from above link]
Description; A characteristic of an oral solid dosage form of a medicinal product, specifying the longest single dimension of the solid dosage form as a physical quantity in the dimension of length (e.g., 3 mm).
Example: SPLSIZE for a rectangular shaped tablet is the length and SPLSIZE for a round shaped tablet is the diameter.
Constraints: The length is always in millimeters and should be rounded to the nearest whole millimeter.
[coming soon]
Images are currently available for only ~5,200 of the 12,000 unique products in Pillbox. Because many medications are relabeled and/or redistributed, which requires a separate drug label, the total number of records in Pillbox is ~30,000.
Images are available in two formats (small/large) and are not returned with output. Use a separate call with %3cimage_id%3e for images.
Full image library downloads are available at http://pillbox.nlm.nih.gov/developer.html#images
Pillbox currently contains images from three sources.
1 – Images with black backgrounds created by NLM prior to the development of the NLM SPLIMAGE specification.
2 – Images with gray backgrounds and rulers conform to the SPLIMAGE specification.
3 – Images with gray backgrounds and no ruler are from the Department of Veterans Affairs (VA), Medication Image Library (there are also several black background images from this image set).
small – 160 × 120
http://pillbox.nlm.nih.gov/assets/small/<image_id>.jpg
large – 1024×768 for NLM images, 640×480 for VA images
http://pillbox.nlm.nih.gov/assets/large/<image_id>.jpg
Examples:
http://pillbox.nlm.nih.gov/assets/small/540920173.jpg
http://pillbox.nlm.nih.gov/assets/large/540920173.jpg
Pillbox will soon add a unique product database, where pills will be grouped by their physical appearance and ingredients. For example, when you search for a round, brown, ibuprofen, that is marked “I2” there will be only match, as opposed to the 40+ matches currently. A link will connect that record to all Pillbox records and drug labels for that particular product.