openFDA: 'openFDA' API

[simpar1471]

Submitting Author Name: Simon Parker
Submitting Author Github Handle: @simpar1471
Repository: https://www.github.com/simpar1471/openFDA
Version submitted: 0.1.0.9000
Submission type: Standard
Editor: @maelle
Reviewers: @tanho63, @nrennie

Archive: TBD
Version accepted: TBD
Language: en

---

• Paste the full DESCRIPTION file inside a code block below:

Package: openFDA
Title: 'openFDA' API
Version: 0.1.0.9000
Authors@R: 
    person("Simon", "Parker", , "simon.parker.24@ucl.ac.uk",
           role = c("aut", "cre", "cph"),
           comment = c(ORCID = "0009-0003-8214-4496"))
Description: The 'openFDA' API facilitates access to U.S. Food and Drug 
    Administration (FDA) data on drugs, devices, foodstuffs, tobacco, and more.
    This package makes the API easily accessible with 'httr2', returning
    objects which the user can convert to JSON data and parse. Kass-Hout TA, Xu
    Z, Mohebbi M et al. (2016) <doi:10.1093/jamia/ocv153>.
License: GPL (>= 3)
URL: https://github.com/simpar1471/openFDA,
    https://simpar1471.github.io/openFDA/
BugReports: https://github.com/simpar1471/openFDA/issues
Depends:
    R (>= 4.1.0)
Imports:
    cli,
    httr2,
    checkmate,
    purrr,
    rlang,
    vctrs
Config/Needs/website: rmarkdown
Suggests: 
    knitr,
    rmarkdown,
    testthat (>= 3.0.0),
    stringr
Config/testthat/edition: 3
Encoding: UTF-8
Roxygen: list(markdown = TRUE)
RoxygenNote: 7.3.2
VignetteBuilder: knitr

Scope

• Please indicate which category or categories from our package fit policies this package falls under: (Please check an appropriate box below. If you are unsure, we suggest you make a pre-submission inquiry.):

  • data retrieval
  • data extraction
  • data munging
  • data deposition
  • data validation and testing
  • workflow automation
  • version control
  • citation management and bibliometrics
  • scientific software wrappers
  • field and lab reproducibility tools
  • database software bindings
  • geospatial data

• Explain how and why the package falls under these categories (briefly, 1-2 sentences):

openFDA retrieves data from the elastic-search based openFDA API, using httr2. The package can be used to query the API on different fields, and successful queries return httr2 response objects with JSON data that R users can manipulate further.

• Who is the target audience and what are scientific applications of this package?

The package is intended for anyone wanting to use the openFDA API through R. These include researchers focused on pharmacovigilance (e.g. with the device adverse event endpoints) or veterinary researchers (e.g. with the animal product adverse event endpoints) - really, any user interested in accessing FDA data.

• Are there other R packages that accomplish the same thing? If so, how does yours differ or meet our criteria for best-in-category?

There are other packages. These include the rOpenHealth/openfda package, in which queries are built up in an httr2-like manner. It automatically converts the response data to data frames, but this package returns the underlying httr2 response object, which users can then choose how to parse themselves. Their package does not have a CI suite, nor a documentation website. There is also ck2136/FDAopenR, which has a test suite with 100% coverage and a now-defunct link to Travis CI. It takes an object-oriented approach which I haven't quite wrapped my head around from looking at the README.

Personally, I prefer 'one function, more parameters' approach in my package - but to each their own. I also believe that this package has a wider and more useful array of error handlers, which point the user to commonly encountered problems with the openFDA API itself. This package is also cleared by the relatively more stringent pkgcheck() checks.

This package is also already on CRAN. I know the guide for authors specifies you'd rather not have it this way round, but I didn't intend to submit the package for review when I first made it.

• (If applicable) Does your package comply with our guidance around Ethics, Data Privacy and Human Subjects Research?

Not applicable

• If you made a pre-submission inquiry, please paste the link to the corresponding issue, forum post, or other discussion, or @tag the editor you contacted.

Not applicable

• Explain reasons for any pkgcheck items which your package is unable to pass.

Everything passes on CI. My functions get_api_key() and set_api_key() are not unique to this package, but I think the names are appropriate to the actions these functions perform.

Technical checks

Confirm each of the following by checking the box.

• I have read the rOpenSci packaging guide.
• I have read the author guide and I expect to maintain this package for at least 2 years or to find a replacement.

This package:

• does not violate the Terms of Service of any service it interacts with.
• has a CRAN and OSI accepted license.
• contains a README with instructions for installing the development version.
• includes documentation with examples for all functions, created with roxygen2.
• contains a vignette with examples of its essential functions and uses.
• has a test suite.
• has continuous integration, including reporting of test coverage.

Publication options

• Do you intend for this package to go on CRAN?

• Do you intend for this package to go on Bioconductor?

• Do you wish to submit an Applications Article about your package to Methods in Ecology and Evolution? If so:

MEE Options

• The package is novel and will be of interest to the broad readership of the journal.
• The manuscript describing the package is no longer than 3000 words.
• You intend to archive the code for the package in a long-term repository which meets the requirements of the journal (see MEE's Policy on Publishing Code)
• (Scope: Do consider MEE's Aims and Scope for your manuscript. We make no guarantee that your manuscript will be within MEE scope.)
• (Although not required, we strongly recommend having a full manuscript prepared when you submit here.)
• (Please do not submit your package separately to Methods in Ecology and Evolution)

Code of conduct

• I agree to abide by rOpenSci's Code of Conduct during the review process and in maintaining my package should it be accepted.

[ropensci-review-bot]

Thanks for submitting to rOpenSci, our editors and @ropensci-review-bot will reply soon. Type @ropensci-review-bot help for help.

[ropensci-review-bot]

🚀

Editor check started

👋

[ropensci-review-bot]

Checks for openFDA (v0.1.0.9000)

git hash: d4930044

• ✔️ Package is already on CRAN.
• ✔️ has a 'codemeta.json' file.
• ✔️ has a 'contributing' file.
• ✔️ uses 'roxygen2'.
• ✔️ 'DESCRIPTION' has a URL field.
• ✔️ 'DESCRIPTION' has a BugReports field.
• ✔️ Package has at least one HTML vignette
• ✔️ All functions have examples.
• ✔️ Package has continuous integration checks.
• ✔️ Package coverage is 76.5%.
• ✔️ R CMD check found no errors.
• ✔️ R CMD check found no warnings.
• 👀 Function names are duplicated in other packages

(Checks marked with 👀 may be optionally addressed.)

Package License: GPL (>= 3)

---

1. Package Dependencies

Details of Package Dependency Usage (click to open)

The table below tallies all function calls to all packages ('ncalls'), both internal (r-base + recommended, along with the package itself), and external (imported and suggested packages). 'NA' values indicate packages to which no identified calls to R functions could be found. Note that these results are generated by an automated code-tagging system which may not be entirely accurate.

type	package	ncalls
internal	base	79
internal	openFDA	30
imports	httr2	11
imports	checkmate	11
imports	rlang	5
imports	cli	4
imports	purrr	2
imports	vctrs	NA
suggests	knitr	NA
suggests	rmarkdown	NA
suggests	testthat	NA
suggests	stringr	NA
linking_to	NA	NA

Click below for tallies of functions used in each package. Locations of each call within this package may be generated locally by running 's <- pkgstats::pkgstats(<path/to/repo>)', and examining the 'external_calls' table.

base

c (30), search (11), call (7), paste0 (5), sort (5), class (4), url (3), list (2), message (2), as.character (1), is.na (1), length (1), mode (1), names (1), paste (1), sub (1), sum (1), switch (1), Sys.getenv (1)

openFDA

check_openFDA_string_arg (4), check_openFDA_int_arg (3), retrieve_openFDA_query (3), endpoint_url (2), format_search_term (2), format_sort_term (2), openFDA_error_handling (2), check_mode_arg (1), check_search_arg (1), check_sort_arg (1), check_warn_on_http_error_arg (1), format_url_component (1), get_api_key (1), openFDA (1), openFDA_err_400_msg (1), openFDA_err_403_msg (1), openFDA_err_404_msg (1), openFDA_err_500_msg (1), openFDA_err_generic_msg (1)

checkmate

test_character (4), test_integerish (3), test_logical (2), test_string (2)

httr2

url_parse (3), request (2), resp_body_json (2), resp_status (2), req_perform (1), resp_status_desc (1)

rlang

caller_env (5)

cli

format_inline (2), cli_warn (1), qty (1)

purrr

imap_chr (2)

NOTE: Some imported packages appear to have no associated function calls; please ensure with author that these 'Imports' are listed appropriately.

---

2. Statistical Properties

This package features some noteworthy statistical properties which may need to be clarified by a handling editor prior to progressing.

Details of statistical properties (click to open)

The package has:

• code in R (100% in 5 files) and
• 1 authors
• 1 vignette
• no internal data file
• 6 imported packages
• 5 exported functions (median 10 lines of code)
• 39 non-exported functions in R (median 12 lines of code)

---

Statistical properties of package structure as distributional percentiles in relation to all current CRAN packages
The following terminology is used:

• loc = "Lines of Code"
• fn = "function"
• exp/not_exp = exported / not exported

All parameters are explained as tooltips in the locally-rendered HTML version of this report generated by the checks_to_markdown() function

The final measure (fn_call_network_size) is the total number of calls between functions (in R), or more abstract relationships between code objects in other languages. Values are flagged as "noteworthy" when they lie in the upper or lower 5th percentile.

measure	value	percentile	noteworthy
files_R	5	31.4
files_vignettes	1	61.5
files_tests	5	75.3
loc_R	438	41.6
loc_vignettes	172	42.4
loc_tests	262	56.9
num_vignettes	1	58.4
n_fns_r	44	51.3
n_fns_r_exported	5	25.5
n_fns_r_not_exported	39	58.8
n_fns_per_file_r	4	65.8
num_params_per_fn	2	8.1
loc_per_fn_r	11	32.6
loc_per_fn_r_exp	10	22.7
loc_per_fn_r_not_exp	12	39.3
rel_whitespace_R	5	17.2
rel_whitespace_vignettes	24	30.5
rel_whitespace_tests	16	49.2
doclines_per_fn_exp	36	43.7
doclines_per_fn_not_exp	0	0.0	TRUE
fn_call_network_size	26	50.7

---

2a. Network visualisation

Click to see the interactive network visualisation of calls between objects in package

---

3. goodpractice and other checks

Details of goodpractice checks (click to open)

3a. Continuous Integration Badges

GitHub Workflow Results

id	name	conclusion	sha	run_number	date
15925186747	check-no-suggests	NA	d49300	13	2025-06-27
15925037198	pages build and deployment	success	8585ca	18	2025-06-27
15925186753	pkgcheck	NA	d49300	5	2025-06-27
15925186738	pkgdown.yaml	NA	d49300	20	2025-06-27
15925186745	R-CMD-check	NA	d49300	19	2025-06-27
15925186746	test-coverage.yaml	success	d49300	14	2025-06-27

---

3b. goodpractice results

R CMD check with rcmdcheck

rcmdcheck found no errors, warnings, or notes

Test coverage with covr

Package coverage: 76.54

Cyclocomplexity with cyclocomp

No functions have cyclocomplexity >= 15

Static code analyses with lintr

lintr found the following 10 potential issues:

message	number of times
Avoid library() and require() calls in packages	2
Lines should not be more than 80 characters. This line is 118 characters.	1
Lines should not be more than 80 characters. This line is 119 characters.	1
Lines should not be more than 80 characters. This line is 121 characters.	1
Lines should not be more than 80 characters. This line is 81 characters.	3
Lines should not be more than 80 characters. This line is 85 characters.	1
Lines should not be more than 80 characters. This line is 90 characters.	1

---

4. Other Checks

Details of other checks (click to open)

✖️ The following 2 function names are duplicated in other packages:

• • get_api_key from ceramic, clockify, DemografixeR, mathpix, polished, Rnumerai, rscopus, rwunderground, twfy
• • set_api_key from cancensus, clockify, googlenlp, newsanchor, polished, Rnumerai, rscopus, rwunderground, tidytransit, twfy

---

Package Versions

package	version
pkgstats	0.2.0.58
pkgcheck	0.1.2.136

---

Editor-in-Chief Instructions:

This package is in top shape and may be passed on to a handling editor

[simpar1471]

Re some findings from the automated checks:

• For pkgcheck note on unused imports: The function vctrs::list_drop_empty() is used in openFDA(), so needs to be imported.
• The lintr issue with using library() or require() I think is coming from the vignettes; there are no library()/require() calls in the package code itself.

[mpadge]

Thanks for your submission @simpar1471. And thanks for explaining those automated checks, but you don't need to worry. The most important checks are the ✔ ones, which in your case indicate that all is good. Thank you also for the links to equivalent packages, from which it's immediately clear that https://github.com/rOpenHealth/openfda should potentially be archived, which we'll now definitely follow up on. But that's also very helpful to indicate the your package is clearly in scope here, and will likely serve as a great replacement and update for the 'openfda' package. I'll ask for further thoughts from the editorial team, and return either with any questions we may have, or by simply assigning an editor to handle the submission.

Oh, and it's also okay to already have the package on CRAN. The review-then-CRAN sequence is only recommended, as packages often undergo extensive changes during review.

[mpadge]

@ropensci-review-bot assign @maelle as editor

[ropensci-review-bot]

Assigned! @maelle is now the editor

[mpadge]

(And apologies there, I mis-read https://github.com/rOpenHealth/openfda as ropensci/openfda, but it's actually nothing to do with us, so I guess we can just kinda ignore that and proceed here?)

[maelle]

(And apologies there, I mis-read rOpenHealth/openfda as ropensci/openfda, but it's actually nothing to do with us, so I guess we can just kinda ignore that and proceed here?)

Not sure what the etiquette is, but it might make sense to open an issue to note that there's a package with the same name that is actively developed and that is now on CRAN?

[maelle]

Thanks a lot for your submission @simpar1471! I have some requests/comments that we can discuss before I look for reviewers. Some of them, especially the ones about the interface, could be left for later once you've heard from reviewers as they might have different opinions and ideas.

Editor checks:

• Documentation: The package has sufficient documentation available online (README, pkgdown docs) to allow for an assessment of functionality and scope without installing the package. In particular,
  • Is the case for the package well made?
  • Is the reference index page clear (grouped by topic if necessary)?
  • Are vignettes readable, sufficiently detailed and not just perfunctory?
• Fit: The package meets criteria for fit and overlap.
• Installation instructions: Are installation instructions clear enough for human users?
• Tests: If the package has some interactivity / HTTP / plot production etc. are the tests using state-of-the-art tooling?
• Contributing information: Is the documentation for contribution clear enough e.g. tokens for tests, playgrounds?
• License: The package has a CRAN or OSI accepted license.
• Project management: Are the issue and PR trackers in a good shape, e.g. are there outstanding bugs, is it clear when feature requests are meant to be tackled?

---

Editor comments

• In the DESCRIPTION file there's the DOI to a publication about the API. Could the text make clearer what the DOI is?
• The most recent pkgcheck CI runs fail: https://github.com/simpar1471/openFDA/actions?query=workflow%3Apkgcheck

These functions do not have examples: [openFDA_options].
The following function has no documented return value: [openFDA_options]

• The docs state "To permanently set the API key for a given project, set OPENFDA_TOKEN in .Renviron." I would actually recommend mentioning the use of the keyring package. Either having it in the docs, or even using it under the hood.

• The set_api_key() could instead take no argument, or support not supplying an argument, and then read the key interactively, using readline() like in gitcreds. Alternatively, if you rely on keyring there'll be a prompt. The advantage of having users enter the key alternatively is that it won't be in their R history or scripts.

• This line if (api_key == "") throw_api_key_error() could be

if (!nzchar(api_key)) throw_api_key_error()

see the docs of the corresponding lintr: https://lintr.r-lib.org/reference/nzchar_linter.html

• Very minor: This line should use -- instead of -.

• In the README I see "With an API key you can make 240 requests per minute, and are limited to 120,000 requests per day.". I think it'd be worth mentioning that your package automatically handles the request rate limiting / throttling.

• In https://github.com/simpar1471/openFDA/blob/e2f59d7e0d65e28bdef601696f615580db043488/R/api_key.R#L45-L52

  cli::cli_abort(
    c("To use {.pkg openFDA}, you must set an openFDA API key.",
      "i" = paste0("Go to <https://open.fda.gov/apis/authentication/> ",
                   "to get an openFDA API key, then supply it to ",
                   "{.fun set_api_key} to cache it for use in this session.")),
    class = "openFDA_no_api_key",
    call = call
  )

could be, for conciseness and for making the URL clickable,

  cli::cli_abort(
    c("To use {.pkg openFDA}, you must set an openFDA API key.",
      "i" = "Go to {.url https://open.fda.gov/apis/authentication/}
            to get an openFDA API key, then supply it to 
            {.fun set_api_key} to cache it for use in this session."
    ),
    class = "openFDA_no_api_key",
    call = call
  )

• More generally there's no need to use paste0() within cli calls.

• While I understand the advantages of the function's returning an httr2 object, I wonder whether your package should also offer a bit more convenience for users that know less about httr2 details. This doesn't need to be settled now unless you want to: the opinion of reviewers will be useful.

• In the main vignette, in "By default, openFDA() will ask you if you want to perform paging, but this tends to break vignettes." you might want to clarify what you mean by performing paging: fetching all pages there are without the user's having to worry about paging.

• Regarding paging, rather than having a special argument, I like the approach of the gh::gh() function where you write .limit = .Inf to get all results.

• If the users deal with paging themselves, how do they enter which page they want to request?

• "We can suppress this warning by setting paging to "no-quiet"" is not intuitive for me because I read it as "not quiet", that is, "verbose". 😸 More on verbosity control: https://ropensci.org/blog/2024/02/06/verbosity-control-packages/

• " The last date at which this openFDA endpoint was updated." made me wonder whether your package should support some sort of caching?

• I wonder whether the meaning of the count argument would be clearer if it were called count_by or count_on.

• Reading "So, for example, a search for drugs with the class "thiazide diuretic" should be formatted as "openfda.pharm_class_epc:"thiazide diuretic""" made me wonder whether the package could provide some helpers to build queries. Then I saw there are such helpers, could they already be mentioned in this example?

• Would it make any sense to make it possible to write queries a bit more like in R

search_term <- format_search_term(c("openfda.generic_name" = "amoxicillin",
                                    "openfda.route" = "oral"),
                                  mode = "and")

would be

search_term <- format_search_term(openfda.generic_name == "amoxicillin",
                                   & openfda.route == "oral")

Similarly format_sort_term(c("openfda.generic_name" = "asc")) could be something like format_sort_term(asc(openfda.generic_name)).

(for instance the glitter package supports a domain-specific language for SPARQL, but then SPARQL is more complicated than what the FDA API requires)

• In any case it'd be nice not to have to use c() in format_search_term(), you could achieve that by using ...and having other arguments' names start with a dot, like in gh::gh().

• Wrong format "[httr2]" in https://github.com/simpar1471/openFDA/blob/e2f59d7e0d65e28bdef601696f615580db043488/vignettes/openFDA.Rmd#L282.

• The intro of https://simpar1471.github.io/openFDA/articles/using_openFDA.html should explain what BNF is.

• The font you currently use for code has ligatures, which might be puzzling for some readers when they see |> as an arrow head.

• if (!inherits(warn_on_http_error, "logical")) { should be if (!is.logical(warn_on_http_error)) {.

• if (!inherits(sort, "character")) { should be if (!is.character(sort)) {. This comes up again at least in https://github.com/simpar1471/openFDA/blob/e2f59d7e0d65e28bdef601696f615580db043488/R/check_args.R#L139-L140.

• On https://github.com/simpar1471/openFDA/blob/e2f59d7e0d65e28bdef601696f615580db043488/R/check_args.R#L167-L168, the condition should use is.numeric(). I'd recommend going through all occurrences of inherits() to see whether there's a base R function covering the case.

• if (param < 1 & vname != "limit") { should be if (param < 1 && vname != "limit") {. You could run this linter: https://lintr.r-lib.org/reference/vector_logic_linter.html. (From a cursory look most conditionals use the right pattern)

• I'm impressed by your using and testing error classes. 👌

• For testing why not use some sort of response caching through {vcr} (check out its development version) or {httptest2}?

• Are the tests calling the API not skipped on CRAN or did I miss something?

---

[simpar1471]

Thanks for the comprehensive set of comments, @maelle.

I've addressed many of the smaller points in commits linked in this comment, and can implement larger changes during the review process.

• Re the pkgcheck failure - I added some examples in simpar1471/openFDA@f031d11, but don't know what to put as return documentation - since the option isn't really a function that returns something. What would you advise?
• The DOI in the DESCRIPTION: fixed in simpar1471/openFDA@7c35388
• I think the keyring package is the best option - can I update the package/docs as required once reviewers are assigned?
• The nzchar() point: fixed in simpar1471/openFDA@68d94b8
• README changes: addressed in simpar1471/openFDA@51b7976
• Removing paste0() in cli calls: fixed in simpar1471/openFDA@94cf79d (with a healthy backlog of code in other projects that has this 🤦‍♂️)
• I'll also wait for package review before adding helpers for the returned objects, but I can see that being useful for end-users (at least some wrappers around httr2::resp_body_json()).
• Describing paging in the main vignette: addressed in simpar1471/openFDA@183c4a8
• The "no-quiet" option for paging. Based on the blog post you attached, it looks like best practice to split the verbosity and paging control up. I was thinking of adding a package-level option named openFDA.verbosity with the valid values something like c("verbose", "quiet") (with "verbose" as the default).
• I'm not sure if it should support a caching system like memoisation, as it is possible (though very unlikely) that updates to the API could occur between calls, and memoisation would prevent the new results from being retrieved. Do you have a link to a package with an example of this functionality? I've checked some of the rOpenSci data access packages but not found a setup to refer to.
• I agree that the argument count would be clearer if renamed to count_by or count_on, but named it count to match onto the openFDA API's field names, which makes me reluctant to change it.
• I've added a note about these search term construction helpers to the example you referred to in simpar1471/openFDA@720ef1e
• I've not made a DSL before, and could give it a try, but would like to hear back from reviewers as to whether they think this would be more useful than your base recommendation of dropping the need for c().
• Fixed 'wrong format "[httr2]"' in simpar1471/openFDA@503ccbb
• Added a (too?) brief note about the BNF in simpar1471/openFDA@7ed99dc
• Changed the font to one without ligatures in simpar1471/openFDA@8771f71
• Removed unneeded inherits() calls in simpar1471/openFDA@3bdfcbd
• Fixed foo & bar occurrences that should've been foo && bar in simpar1471/openFDA@9fc2b64
• I'd happily implement a vcr-enabled test suite over the process of the review. This could aid security, e.g. by supplying the API key under the Authorization header instead of including it in the request URLs. Edit: Moved API key to Auth header in simpar1471/openFDA@10e95ed
• Tests calling the API are automatically skipped by httr2::secret_has_key(), which automatically testthat::skip() tests when the env var "OPENFDA_KEY" is missing.