An official website of the United States Government
Learn

API basics

OpenFDA is a powerful ElasticSearch-based API that may be different from other APIs you’ve used. Here you can learn about the query syntax, including your API key, and other tips for searching any of the openFDA endpoints.

About the openFDA API

OpenFDA is an Elasticsearch-based API that serves public FDA data about nouns like drugs, devices, and foods.

Each of these nouns has one or more endpoints, which serve unique data—such as data about recall enforcement reports, or about adverse events. Every query to the API must go through one endpoint for one kind of data.

Not all data in openFDA has been validated for clinical or production use. And because openFDA only serves publicly available data, it does not contain data with Personally Identifiable Information about patients or other sensitive information.

The API returns individual results as JSON by default. The JSON object has two sections:

  • meta: Metadata about the query, including a disclaimer, link to data license, last-updated date, and total matching records, if applicable.

  • results: An array of matching results, dependent on which endpoint was queried.

Try the API

The following example is a query for one report of an adverse drug event. In other words, it is a query for a single record from the adverse event endpoint for drugs.

Example API query

One drug adverse event report

This query searches in the drug/event endpoint for a single record, and returns it. The record contains all kinds of information about the adverse event report, including the drugs that the patient was taking, the reactions that the patient experienced, and a good deal of other context.

Each endpoint has its own unique fields, particular to the kind of data that it serves.

Anatomy of a response

Responses for non-count queries are divided into two sections, meta and results.

Meta

For non-count queries, the meta section includes a disclaimer, a link to the openFDA data license, and information about the results that follow.

  • meta.disclaimer
    string

    Important details notes about openFDA data and limitations of the dataset.

  • meta.license
    string

    Link to a web page with license terms that govern data within openFDA.

  • meta.last_updated
    string

    The last date when this openFDA endpoint was updated. Note that this does not correspond to the most recent record for the endpoint or dataset. Rather, it is the last time the openFDA API was itself updated.

  • meta.results.skip
    number

    Offset (page) of results, defined by the skip query parameter.

  • meta.results.limit
    number

    Number of records in this return, defined by the limit query parameter. If there is no limit parameter, the API returns one result.

  • meta.results.total
    number

    Total number of records matching the search criteria.

Results

For non-count queries, the results section is an array of matching records.

Query parameters

The API supports four query parameters. The basic building block of queries is the search parameter. Use it to "filter" requests to the API by looking in specific fields for matches. Each endpoint has its own unique fields that can be searched.

  • search: What to search for, in which fields. If you don’t specify a field to search, the API will search in every field.

  • count: Count the number of unique values of a certain field, for all the records that matched the search parameter. By default, the API returns the 1000 most frequent values.

  • limit: Return up to this number of records that match the search parameter. Large numbers (above 100) could take a very long time, or crash your browser.

  • skip: Skip this number of records that match the search parameter, then return the matching records that follow. Use in combination with limit to paginate results.

Query syntax

Queries to the openFDA API are made up of parameters joined by an ampersand &. Each parameter is followed by an equals sign = and an argument.

Searches have a special syntax: search=field:term. Note that there is only one equals sign = and there is a colon : between the field to search, and the term to search for.

Here are a few syntax patterns that may help if you’re new to this API.

  • search=field:term: Search within a specific field for a term.

  • search=field:term+AND+field:term: Search for records that match both terms.

  • search=field:term+field:term: Search for records that match either of two terms.

  • search=field:term&count=another_field: Search for matching records. Then within that set of records, count the number of times that the unique values of a field appear. Instead of looking at individual records, you can use the count parameter to count how often certain terms (like drug names or patient reactions) appear in the matching set of records.

Here are some example queries that demonstrate how these searches and the count parameter work, all using the drug adverse events endpoint.

Example API query

Matching a single search term

This query looks in the drug/event endpoint for a record where one of the reported patient reactions was fatigue.

  1. Search for records where the field patient.reaction.reactionmeddrapt (patient reaction) contains fatigue

Example API query

Matching all search terms

This query looks in the drug/event endpoint for a record where both fatigue was a reported patient reaction and the country in which the event happened was Canada. The key here is the +AND+ that joins the two search terms.

  1. Search for records where the field patient.reaction.reactionmeddrapt (patient reaction) contains fatigue and occurcountry (country where the event happened) was ca (the country code for Canada)

Example API query

Matching any search terms

This query looks in the drug/event endpoint for a record where either fatigue was a reported patient reaction or the country in which the event happened was Canada.

  1. Search for records where the field patient.reaction.reactionmeddrapt (patient reaction) contains fatigue or occurcountry (country where the event happened) was ca (the country code for Canada)

Example API query

Counting records where certain terms occur

This query looks in the drug/event endpoint for all records. It then returns a count of the top patient reactions. For each reaction, the number of records that matched is summed, providing a useful summary.

  1. Search for all records

  2. Count the number of records matching the terms in patient.reaction.reactionmeddrapt.exact. The .exact suffix here tells the API to count whole phrases (e.g. injection site reaction) instead of individual words (e.g. injection, site, and reaction separately)

Spaces

Queries use the plus sign + in place of the space character. Wherever you would use a space character, use a plus sign instead.

Phrase matches

For phrase matches, use double quotation marks " " around the words. For example, "multiple+myeloma".

Grouping

To group several terms together, use parentheses ( ). For example, (patient.drug.medicinalproduct:cetirizine+loratadine+diphenhydramine). Terms separated by plus signs + are treated as in a boolean OR.

To join terms as in a boolean AND, use the term +AND+. For example, (patient.drug.medicinalproduct:cetirizine+loratadine+diphenhydramine)+AND+serious:2 requires that any of the drug names match and that the field serious also match.

Dates and ranges

The openFDA API supports searching by range in date, numeric, or string fields.

  • Specify an inclusive range by using square brackets [min+TO+max]. These include the values in the range. For example, [1+TO+5] will match 1 through 5.

  • Dates are simple to search by via range. For instance, [2004-01-01+TO+2005-01-01] will search for records between Jan 1, 2004 and Jan 1, 2005.

Missing (or not missing) values

  • _missing_: search modifier that matches when a field has no value (is empty).

  • _exists_: search modifier that matches when a field has a value (is not empty).

Example API query

Data is missing from a field

This query looks in the drug/event endpoint for records that are missing a company number, meaning that the report was submitted directly by a member of the public and not through a drug manufacturer.

  1. Search for records where the field companynumb is missing or empty

Example API query

Data in a field is present, regardless of the value

This query looks in the drug/event endpoint for records that have a company number, meaning that the report was submitted through a drug manufacturer.

  1. Search for records where the field companynumb has data in it

Timeseries

The API supports count on date fields, which produces a timeseries at the granularity of day. The API returns a complete timeseries.

Example API query

Counting by date, returning a timeseries

This query looks in the drug/event endpoint for all records. It then returns a count of records per day, according to a certain date field (the receipt date of the adverse event report).

  1. Search for all records

  2. Count the number of records per day, according to the field receiptdate