Skip to contents

Send requests to the openFDA API

Source: R/openFDA.R
openFDA.Rd

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

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. The openFDA website has more information on how to count 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 than 1000 (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").

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 with set_api_key(), or openFDA() will not work.

paging

A single string describing whether results should be paged. openFDA() uses the value of the package-level option openFDA.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 with openFDA_options(). Permissible values for paging_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 option openFDA.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 with openFDA_options(). Permissible values for paging_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 option openFDA.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 with openFDA_options(). Permissible values for handle_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 (26712 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.