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(),
paging = current_openFDA_options()[["openFDA.paging"]],
paging_verbosity = current_openFDA_options()[["openFDA.paging_verbosity"]],
handle_http_errors = current_openFDA_options()[["openFDA.handle_http_errors"]]
)
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 ofsearch
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]"
, orc("[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. The openFDA website has more information on how tocount
by a specific field.- limit
A single integerish value describing the limit on the number of records to retrieve. An error will be thrown if
limit
is more than1000
(the default).- skip
A single integerish value 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 (case-sensitive). By default,
openFDA()
targets the Drugs@FDA endpoint ("drugs-drugsfda"
)."animalandveterinary-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."drug-shortages"
: Data on drug shortages as compiled by the FDA."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-registrationlisting"
: 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.
- api_key
A single-length character vector with your openFDA API key. By default this is the result of
get_api_key()
. You must set this withset_api_key()
, oropenFDA()
will not work.- paging
A single string describing whether results should be paged.
openFDA()
uses the value of the package-level optionopenFDA.paging
for this argument, but you can set this behaviour on a per-function call level with this parameter. You can edit the option itself withopenFDA_options()
. Permissible values forpaging_verbosity
include:"ask"
-openFDA()
will warn you that pagination is required and ask if you want this to be done. Depending on user input, either a single httr2 response object or a list of httr2 response objects will be returned. This will throw an error if your R session is not in interactive mode."always"
-openFDA()
will always perform pagination. A list of httr2 responses will be returned when pagination occurs."never"
-openFDA()
will never perform pagination. Only the first httr2 response will be returned.
- paging_verbosity
A single string describing whether messages about pagination should be printed to the console.
openFDA()
uses the value of the package-level optionopenFDA.paging_verbosity
for this argument, but you can set this behaviour on a per-function call level with this parameter. You can edit the option itself withopenFDA_options()
. Permissible values forpaging_verbosity
include:"verbose"
- If paging can be performed, print a message to the console, stating how many requests are required with a minimum estimate for the time this will take."quiet"
- Even if paging can be performed, do not print messages about it to the console.
- handle_http_errors
A single string defining how to handle HTTP codes other than
200 OK
.openFDA()
uses the value of the package-level optionopenFDA.handle_http_errors
for this argument, but you can set this behaviour on a per-function call level with this parameter. You can edit the option itself withopenFDA_options()
. Permissible values forhandle_http_errors
include:"warn"
: If the returned HTTP code is not 200, issue a warning to the console and return the underlying httr2 response object."error"
: If the returned HTTP code is not 200, throw an (informative) error."silent"
: If the returned HTTP code is not 200, return the underlying httr2 response object without printing a warning.
Value
Either an httr2 response object from
httr2::req_perform()
or list of these objects, depending on whether
pagination was required. You can use httr2::resp_body_json()
to extract
JSON data from these responses.
Note
openFDA()
caches its results with memoise::memoise()
. Consequently, you
should find that repeated, identical queries run faster than the first query,
assuming you don't change your query parameters.
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
Read the docs for set_api_key()
to learn how to set your openFDA
API key. Check out format_search_term()
to see 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,
paging = "never",
paging_verbosity = "quiet")
# The function returns an `httr2` object
print(resp)
}
#> Warning: Selecting ‘env’ backend. Secrets are stored in environment variables
#> Warning: Selecting ‘env’ backend. Secrets are stored in environment variables
#> ! OpenFDA API key set.
#> ℹ You can retrieve the key with the following code:
#> `keyring::key_get(service = "OPENFDA_KEY", user = "openFDA")`
#> Warning: Selecting ‘env’ backend. Secrets are stored in environment variables
#> Warning: Selecting ‘env’ backend. Secrets are stored in environment variables
#> Warning: Selecting ‘env’ backend. Secrets are stored in environment variables
#> Warning: Selecting ‘env’ backend. Secrets are stored in environment variables
#> <httr2_response>
#> GET
#> https://api.fda.gov/drug/drugsfda.json?search=openfda.manufacturer_name:gilead%2A&limit=2&skip=10
#> Status: 200 OK
#> Content-Type: application/json
#> Body: In memory (15527 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)
)
#> Error in (function (search = "", sort = NULL, count = NULL, limit = 1000, :
#> ! The `paging` argument must not be `"ask"` if R is not running
#> interactively.