An official website of the United States Government
Learn

API reference

Going beyond the basics? This reference can help you understand more about the technical details of the openFDA APIs.

Downloads

OpenFDA is designed primarily for real-time queries. However, some applications may require all the data served by an endpoint, or exceed the query limits or result limit (25000 records per query) in place to promote equitable access and manage load on the system.

Because openFDA is open source and its source code is available on GitHub, you can create your own instance of openFDA without these limits and run it on your own server. You can also download the data for any openFDA endpoint, in exactly the same JSON format that query results follow, and build your own custom application that uses these JSON files. Because the format is exactly the same as API query results, you can reuse existing code that you’ve written for applications that process openFDA data. There are two things you should know about these downloads.

  • Downloads are broken into parts. Some endpoints have millions of records. For those endpoints, the data are broken up into many small parts. So while some endpoints have all their data available in a single file, others have dozens of files. Each file is a zipped JSON file.

  • To keep your downloaded data up to date, you need to re-download the data every time it is updated. Every time an endpoint is updated (which happens on a regular basis), it is possible that every record has changed, due to corrections or enhancements. That means that you cannot simply download "new" files to keep your downloaded version up to date. You need to download all available data files for the endpoint of interest.

How to download data

There are three ways to download data from openFDA.

  • Download manually. All downloadable files are available on this page. Additionally, there’s a downloads section on each endpoint’s openFDA page—for example, drug adverse event downloads. There you can download a sampling of the data, or all of it, one file at a time.

  • Write code to download the data automatically. A json containing links to all downloadable files is available at here. The data files are hosted at http://download.open.fda.gov/.

  • Synchronize with the openFDA S3 bucket. Both current and old (archived) data files are available at s3://download.open.api.gov, in subdirectories by date (e.g. s3://download.open.fda.gov/2015-12-19/). This is the only place that old data files are hosted.

Download API fields

{
  "meta": {
    "disclaimer": "openFDA is a beta research project and not for clinical use. While we make every effort to ensure that data is accurate, you should assume all results are unvalidated.",
    "license": "http://open.fda.gov/license",
    "last_updated": "2015-12-19"
  },
  "results": {
    "device": {
      "event": {
        "total_records": 33128,
        "export_date": "2015-12-19",
        "partitions": [
          {
            "size_mb": "0.56",
            "records": 795,
            "display_name": "2012 q2 (all)",
            "file": "http://download.open.fda.gov/device/event/2012q2/device-event-0001-of-0001.json.zip"
          },
          {
            "size_mb": "0.58",
            "records": 825,
            "display_name": "2012 q3 (all)",
            "file": "http://download.open.fda.gov/device/event/2012q3/device-event-0001-of-0001.json.zip"
          },
          {
            "…": "…"
          }
        ]
      }
    }
  }
}
  • meta
    string

    This section contains a disclaimer and license information. The field last_updated indicates when the data files were exported.

  • results
    string

    This section has an object for each of the openFDA nouns, and each of those has a child object for each endpoint. For example, for the device/event endpoint, there is a results.device.event object.

Endpoint

The following fields are present for each endpoint—e.g. results.device.event.

  • total_records
    number

    The total number of records in the endpoint.

  • export_date
    number

    The date when the data files for this endpoint were exported.

  • partitions
    array of objects

    The list of data files available for this endpoint. Each object in this list represents a single data file. Some endpoints have just one item in this list, but others have dozens of items.

Partitions

The following fields are present for each object in the partitions list. Remember that each object represents a single file available for download.

  • size_mb
    string

    The size of the file, in megabytes (MB).

  • records
    integer

    The number of records in this file.

  • file
    integer

    A URL at which the file can be accessed.

Authentication

An API key is required to make calls to the openFDA API. The key is free of charge. Your use of the API may be subject to certain limitations on access, calls, or use. These limitations are designed to manage load on the system, promote equitable access, and prevent abuse. Here are openFDA’s standard limits:

  • With no API key: 40 requests per minute, per IP address. 1000 requests per day, per IP address.

  • With an API key: 240 requests per minute, per key. 120000 requests per day, per key.

If you anticipate usage above the limits provided by an API key, please contact us. We’ll work with you to figure out a good solution to your requirements. Signing up for an API key means you agree to our terms of service.

Using your API key

Your API key should be passed to the API as the value of the api_key parameter. Include it before other parameters, such as the search parameter. For example:

https://api.fda.gov/drug/event.json?api_key=yourAPIKeyHere&search=...

Get your API key

We require API keys above a certain number of requests to manage load on the system, promote equitable access, and prevent abuse. See more about how to use your API key.

Signing up for an API key means you agree to our terms of service.

HTTPS requests only

OpenFDA requires you to use https://api.fda.gov for all queries to ensure secure communication.

OpenFDA fields

Different datasets use different drug identifiers—brand name, generic name, NDA, NDC, etc. It can be difficult to find the same drug in different datasets. And some identifiers, like pharmacologic class, are useful search filters but not available in all datasets.

OpenFDA features harmonization on drug identifiers, to make it easier to both search for and understand the drug products returned by API queries. These additional fields are attached to records in all endpoints, if applicable.

When you query an endpoint, you can search by:

  • Fields native to records served by that endpoint.

  • Harmonized openfda fields, if they exist.

OpenFDA does not rewrite original records. These additional fields are annotations, in special openfda dictionary of values.

disclaimer

Limits of openFDA harmonization

Not all records have harmonized fields. Because the harmonization process requires an exact match, some drug products cannot be harmonized in this fashion—for instance, if the drug name is misspelled. Some drug products will have openfda sections, while others will never, if there was no match during the harmonization process. Conversely, searching in these fields will only return a subset of records from a given endpoint.

The documentation below describes fields that you may find in an openfda section of an API result. They are organized by the dataset from which they originate.

NDC

NDC stands for National Drug Code. The Drug Listing Act of 1972 requires registered drug establishments to provide the FDA with a current list of all drugs manufactured, prepared, propagated, compounded, or processed by it for commercial distribution. (See Section 510 of the Federal Food, Drug, and Cosmetic Act (Act) (21 U.S.C. § 360)).

Drug products are identified and reported using a unique, three-segment number, called the National Drug Code (NDC), which serves as a universal product identifier for drugs.

Several NDC dataset fields are used to annotate records in openFDA.

  • application_number
    array of strings

    This corresponds to the NDA, ANDA, or BLA number reported by the labeler for products which have the corresponding Marketing Category designated. If the designated Marketing Category is OTC Monograph Final or OTC Monograph Not Final, then the application number will be the CFR citation corresponding to the appropriate Monograph (e.g. “part 341”). For unapproved drugs, this field will be null.

  • brand_name
    array of strings

    The brand or trade name of the product.

  • dosage_form
    array of strings

    The dosage form of the drug product.

  • generic_name
    array of strings

    The dosage form of the drug product.

  • manufacturer_name
    array of strings

    Name of company corresponding to the labeler code segment of the NDC.

  • product_ndc
    array of strings

    The labeler manufacturer code and product code segments of the NDC number, separated by a hyphen.

  • product_type
    array of strings

    The route of administration of the drug product.

  • route
    array of strings

    The type of drug product.

  • substance_name
    array of strings

    The list of active ingredients of a drug product.

SPL

SPL stands for the Structured Product Labeling standard approved by Health Level Seven (HL7) and adopted by FDA as a mechanism for exchanging product and facility information. Drug products have associated labels that confirm to the SPL format.

Several SPL dataset fields are used to annotate records in openFDA.

  • spl_id
    array of strings

    A unique identifier for a particular version of a Structured Product Label for a product. Also referred to as the document ID.

  • spl_set_id
    array of strings

    A unique identifier for the Structured Product Label for a product, which is stable across versions of the label.

  • pharm_class_moa
    array of strings

    Mechanism of action. Molecular, subcellular, or cellular level functional activity of a drug product’s pharmacologic class.

  • pharm_class_cs
    array of strings

    Chemical structure. Chemical structure classification of a pharmacologic class.

  • pharm_class_pe
    array of strings

    Physiologic effect. Tissue, organ, or organ system level functional activity of a pharmacologic class.

  • pharm_class_epc
    array of strings

    Established pharmacologic class. A pharmacologic class associated with an approved indication of an active moiety that the FDA has determined to be scientifically valid and clinically meaningful.

  • upc
    array of strings

    Documentation forthcoming.

UNII

UNII stands for Unique Ingredient Identifier. The overall purpose of the joint FDA/USP Substance Registration System (SRS) is to support health information technology initiatives by generating unique ingredient identifiers (UNIIs) for substances in drugs, biologics, foods, and devices. The UNII is a non- proprietary, free, unique, unambiguous, non semantic, alphanumeric identifier based on a substance’s molecular structure and/or descriptive information.

  • unii
    array of strings

    The Unique Ingredient Identifier of the drug or substance.

RxNorm

RxNorm is a normalized naming system for generic and branded drugs; and a tool for supporting semantic interoperation between drug terminologies and pharmacy knowledge base systems. The National Library of Medicine (NLM) produces RxNorm.

  • rxcui
    array of strings

    The RxNorm Concept Unique Identifier. RxCUI is a unique number that describes a semantic concept about the drug product, including its ingredients, strength, and dosage forms.