| Title: | Query the 'NHS TRUD API' |
| Version: | 0.2.0 |
| Description: | Provides a convenient R interface to the 'National Health Service NHS Technology Reference Update Distribution (TRUD) API', allowing users to list available releases for their subscribed items, retrieve metadata, and download release files. For more information on the API, seehttps://isd.digital.nhs.uk/trud/users/guest/filters/0/api. |
| License: | MIT + file LICENSE |
| Encoding: | UTF-8 |
| RoxygenNote: | 7.3.2 |
| Depends: | R (≥ 4.2.0) |
| Imports: | cli, dplyr, httr2, purrr, rlang, rvest, stringr, tibble |
| URL: | https://docs.ropensci.org/trud/,https://github.com/ropensci/trud |
| BugReports: | https://github.com/ropensci/trud/issues |
| Suggests: | knitr, rmarkdown, spelling, testthat (≥ 3.0.0), withr |
| Config/testthat/edition: | 3 |
| Language: | en-US |
| VignetteBuilder: | knitr |
| NeedsCompilation: | no |
| Packaged: | 2025-08-18 20:30:05 UTC; alasdair |
| Author: | Alasdair Warwick [aut, cre, cph], Robert Luben [aut], Abraham Olvera-Barrios [aut], Chuin Ying Ung [aut], Jon Clayden [rev], Alexandros Kouretsis [rev] |
| Maintainer: | Alasdair Warwick <alasdair.warwick.19@ucl.ac.uk> |
| Repository: | CRAN |
| Date/Publication: | 2025-08-18 20:50:02 UTC |
trud: Query the 'NHS TRUD API'
Description
Provides a convenient R interface to the 'National Health Service NHS Technology Reference Update Distribution (TRUD) API', allowing users to list available releases for their subscribed items, retrieve metadata, and download release files. For more information on the API, seehttps://isd.digital.nhs.uk/trud/users/guest/filters/0/api.
Author(s)
Maintainer: Alasdair Warwickalasdair.warwick.19@ucl.ac.uk (ORCID) [copyright holder]
Authors:
Other contributors:
Jon Clayden (ORCID) [reviewer]
Alexandros Kouretsis [reviewer]
See Also
Useful links:
Report bugs athttps://github.com/ropensci/trud/issues
Download NHS TRUD item
Description
Downloads files for a specified NHS TRUD item. By default this downloadsthe latest release. Use theitem numbers fromtrud_items() orget_subscribed_metadata().
Subscription Required
You must subscribe to TRUD items individually through the NHS TRUD websitebefore you can access them usingget_item_metadata() ordownload_item().Simply having an API key is not sufficient. To see items you're alreadysubscribed to, useget_subscribed_metadata(). To browse all availableitems, usetrud_items().
Usage
download_item( item, directory = ".", file_type = c("archive", "checksum", "signature", "publicKey"), release = NULL, overwrite = FALSE)Arguments
item | An integer, the item to be downloaded. Get these from |
directory | Path to the directory to which this item will be downloadedto. This is set to the current working directory by default. |
file_type | The type of file to download. Options are |
release | The release ID to be downloaded. Release IDs are found in the |
overwrite | If |
Value
The file path to the downloaded file, returned invisibly.
Working with specific releases
To download a specific (non-latest) release:
Use
get_item_metadata()withrelease_scope = "all"to retrieve metadata for all releasesThe release IDs are stored under the
iditem for each releasePass the desired release ID to the
releaseparameter ofdownload_item()
See Also
trud_items()to find item numbersget_subscribed_metadata()to see items you can accessget_item_metadata()to explore available releases before downloading
Examples
# Download Community Services Data Set pre-deadline extract XML Schemax <- download_item(394, directory = tempdir())# List downloaded filesunzip(x, list = TRUE)# Download a previous release# First get all releases to see available optionsmetadata <- get_item_metadata(394, release_scope = "all")release_id <- metadata$releases[[2]]$idy <- download_item(394, directory = tempdir(), release = release_id)unzip(y, list = TRUE)# Overwrite existing files if neededz <- download_item(394, directory = tempdir(), overwrite = TRUE)# An informative error is raised if your API key is invalid or missingtry(withr::with_envvar(c("TRUD_API_KEY" = ""), download_item(394)))Retrieve metadata for a NHS TRUD item
Description
Sends a request to the release list endpoint, returning a list of metadatapertaining to the specified NHS TRUD item. Use theitem numbers fromtrud_items() orget_subscribed_metadata().
Subscription Required
You must subscribe to TRUD items individually through the NHS TRUD websitebefore you can access them usingget_item_metadata() ordownload_item().Simply having an API key is not sufficient. To see items you're alreadysubscribed to, useget_subscribed_metadata(). To browse all availableitems, usetrud_items().
Usage
get_item_metadata(item, release_scope = c("all", "latest"))Arguments
item | An integer, the item to be downloaded. Get these from |
release_scope | Which releases to retrieve metadata for. Use |
Value
A list containing item metadata, including release information thatcan be used withdownload_item(). Release IDs for specific downloads arein theid field of each release.
See Also
trud_items()to find item numbersget_subscribed_metadata()to see items you can accessdownload_item()to download files using this metadata
Examples
# Get metadata for Community Services Data Set pre-deadline extract XML Schemaget_item_metadata(394) |> # Display structure without showing sensitive API keys in URLs purrr::map_at("releases", \(release) purrr::map(release, names))# Include metadata for any previous releases using `release_scope = "all"`get_item_metadata(394, release_scope = "all") |> # Display structure without showing sensitive API keys in URLs purrr::map_at("releases", \(release) purrr::map(release, names))# An informative error is raised if your API key is invalid or missingtry(withr::with_envvar(c("TRUD_API_KEY" = ""), get_item_metadata(394)))Get metadata for subscribed NHS TRUD items
Description
A convenience wrapper aroundtrud_items() andget_item_metadata(),retrieving metadata for only items that the user is subscribed to. This isparticularly useful for seeing what data you can download withdownload_item().If you need access to additional items, browse available options withtrud_items(), then subscribe through the NHS TRUD website.
Usage
get_subscribed_metadata(release_scope = c("all", "latest"))Arguments
release_scope | Which releases to retrieve metadata for. Use |
Value
A tibble, with item metadata stored in the list columnmetadata.Use theitem_number column values withdownload_item().
See Also
trud_items()to browse all available itemsget_item_metadata()for detailed metadata on specific itemsdownload_item()to download items you're subscribed to
Examples
# Get metadata for all subscribed items subscribed <- get_subscribed_metadata() # Show structure without exposing API keys in URLs subscribed$metadata[[1]] |> purrr::map_at("releases", \(release) purrr::map(release, names))Get available NHS TRUD items
Description
Scrapesthis pagefrom the NHS TRUD website for all available items. Theitem_number columnin the result contains the identifiers you need forget_item_metadata()anddownload_item().
Subscription Required
You must subscribe to TRUD items individually through the NHS TRUD websitebefore you can access them usingget_item_metadata() ordownload_item().Simply having an API key is not sufficient. To see items you're alreadysubscribed to, useget_subscribed_metadata(). To browse all availableitems, usetrud_items().
Usage
trud_items()Value
A tibble, with columnsitem_number anditem_name. Use theitem_number values as arguments toget_item_metadata() anddownload_item().
See Also
get_subscribed_metadata()to see only items you're subscribed toget_item_metadata()to get detailed information about a specific itemdownload_item()to download files for a specific item
Examples
trud_items()