Send requests to the openFDA API

Send requests to the openFDA API

Usage

openFDA(
  search = "",
  sort = NULL,
  count = NULL,
  limit = 1000,
  skip = NULL,
  endpoint = "drug-drugsfda",
  api_key = get_api_key(),
  warn_on_http_error = TRUE
)

Arguments

search

A character vector which will be passed to format_search_term(). If search is "" (the default), openFDA will retrieve all records with no filtering. An error will be thrown if any elements of search are missing (NA).

sort

A single string or scalar named character vector describing how to sort the results. The sort term should either be formatted as "[FIELD]:[asc/desc]", or c("[FIELD]" = "[asc/desc]"). For example, to sort results in the Drugs@FDA endpoint by ascending submission status dates. If values other than "asc", or "desc" are supplied, the function will throw an error.

count

A single string denoting a field on which to count results. If NULL (the default), results will be returned in full to the user. Specify this parameter if you want to count occurrences of results within your search term - go to https://open.fda.gov/apis/query-syntax/ for more information.

limit

A single integerish value describing the limit on the number of records to retrieve. An error will be thrown if limit is more than 1000 (the default).

skip

A single integer describing how many records should be skipped. If more records are skipped than are found in your search, the openFDA API will return a 404 error.

endpoint

A single-length character vector describing which openFDA endpoint to target.

• "animal-event": Adverse event reports for animal/veterinary drugs.

• "drug-event": Adverse event reports from FDA Adverse Event Reporting System

• "drug-label": Drug documentation in the Structured Product Labeling (SPL) format.

• "drug-ndc": Data from the National Drug Code Directory (NDC).

• "drug-enforcement": Data from the FDA Recall Enterprise System about drug products.

• "drug-drugsfda": Data on products approved for human use by the FDA since 1939, with mostly complete data after 1998.

• "device-510k": Data from 510(k) submissions to the FDA regarding medical devices.

• "device-classification": Data from the FDA Product Classification Database for medical devices.

• "device-enforcement": Data from the FDA Recall Enterprise System (RES) for medical devices.

• "device-event": Data on adverse events associated with FDA-approved medical devices.

• "device-pma": Pre-market approval data for medical devices submitted to the FDA.

• "device-recall": Data on product recalls for medical devices which violate FDA law.

• "device-reglist": Data on FDA Device Registrations and Listings.

• "device-covid19serology": Data from independent evaluations of COVID-19 serological tests.

• "device-udi": Data from the FDA's Global Unique Device Identification Database (GUDID).

• "food-enforcement": Data from the FDA Recall Enterprise System for food products.

• "food-event": Data from the Center for Food Safety and Applied Nutrition Adverse Event Reporting System.

• "other-historicaldocument": The majority of FDA Press Releases, from 1913 to 2014.

• "other-nsde": Data from the National Drug Code Structured Product Labeling Data Elements.

• "other-substance": Data regarding substances - individual molecules, proteins, nucleic acids, and more.

• "other-unii": Data from the FDA's Global Substance Registration System.

• "tobacco-problem": Data on problems (e.g. damage, defects, contamination, bad smell) with tobacco products.

This argument is case-sensitive. By default, the package will target the Drugs@FDA endpoint ("drugs-drugsfda").

api_key

A single-length character vector with your openFDA API key. By default this is the result of get_api_key(). If api_key is an empty string, an error will be thrown.

warn_on_http_error

A scalar logical value. If TRUE (the default), common openFDA HTTP errors will cause explanatory warnings to be printed If FALSE, the underlying httr2 response object will be returned with no extra warnings.

Value

An httr2 response object from httr2::req_perform(). You can use httr2::resp_body_json() to extract JSON data from the response.

References

Kass-Hout TA, Xu Z, Mohebbi M, Nelsen H, Baker A, LEvine J, Johansen E, Bright RA. OpenFDA: an innovative platform providing access to a wealth of FDA's publicly available data J Am Med Inform Assoc 2016, 23(3):596-600. doi:10.1093/jamia/ocv153

See also

format_search_term() documents how input search vectors are converted to openFDA API searches.

Examples

if (httr2::secret_has_key("OPENFDA_KEY")) {
  set_api_key(httr2::secret_decrypt(
    "TEaDtqdFMq9_Montij5p9IY6T57IyqkbF8IYFVOpk-ttxotFUNdJSxgccAnkq4nQhplaf-r3deQ",
    "OPENFDA_KEY"
  ))

  resp <- openFDA(search = "openfda.manufacturer_name:gilead*",
                  limit = 2,
                  skip = 10)

  # The function returns an `httr2` object
  print(resp)
}
#> <httr2_response>
#> GET
#> https://api.fda.gov/drug/drugsfda.json?api_key=[API_KEY]&search=openfda.manufacturer_name:gilead%2A&limit=2&skip=10
#> Status: 200 OK
#> Content-Type: application/json
#> Body: In memory (44050 bytes)

# Bad inputs will cause informative errors - here, a bad API key is supplied
try(
  openFDA(search = "openfda.manufacturer_name:gilead*",
          api_key = "BAD_API_KEY",
          limit = 1)
)
#> Warning: The openFDA API returned a 403 error.
#> ! This usually means that an invalid `api_key` was used.
#> ℹ Your API key was "BAD_API_KEY".
#> <httr2_response>
#> GET
#> https://api.fda.gov/drug/drugsfda.json?api_key=[API_KEY]&search=openfda.manufacturer_name:gilead%2A&limit=1
#> Status: 403 Forbidden
#> Content-Type: application/json
#> Body: In memory (136 bytes)