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, see https://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 ORCID iD [aut, cre, cph], Robert Luben ORCID iD [aut], Abraham Olvera-Barrios ORCID iD [aut], Chuin Ying Ung ORCID iD [aut], Jon Clayden ORCID iD [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

logo

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, see https://isd.digital.nhs.uk/trud/users/guest/filters/0/api.

Author(s)

Maintainer: Alasdair Warwick alasdair.warwick.19@ucl.ac.uk (ORCID) [copyright holder]

Authors:

Other contributors:

See Also

Useful links:

Download NHS TRUD item

Description

Downloads files for a specified NHS TRUD item. By default this downloads the latest release. Use the item numbers from trud_items() or get_subscribed_metadata().

Subscription Required

You must subscribe to TRUD items individually through the NHS TRUD website before you can access them using get_item_metadata() or download_item(). Simply having an API key is not sufficient. To see items you're already subscribed to, use get_subscribed_metadata(). To browse all available items, use trud_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 trud_items() or get_subscribed_metadata().

directory

Path to the directory to which this item will be downloaded to. This is set to the current working directory by default.

file_type

The type of file to download. Options are "archive" (the main release file), "checksum", "signature", or "publicKey". Defaults to "archive".

release

The release ID to be downloaded. Release IDs are found in the id field of each release from get_item_metadata(). If NULL (default), the latest item release will be downloaded.

overwrite

If TRUE, existing files will be overwritten. If FALSE (default), existing files will be skipped and the function will return the existing file path.

Value

The file path to the downloaded file, returned invisibly.

Working with specific releases

To download a specific (non-latest) release:

  1. Use get_item_metadata() with release_scope = "all" to retrieve metadata for all releases

  2. The release IDs are stored under the id item for each release

  3. Pass the desired release ID to the release parameter of download_item()

See Also

Examples


# Download Community Services Data Set pre-deadline extract XML Schema
x <- download_item(394, directory = tempdir())

# List downloaded files
unzip(x, list = TRUE)

# Download a previous release
# First get all releases to see available options
metadata <- get_item_metadata(394, release_scope = "all")
release_id <- metadata$releases[[2]]$id

y <- download_item(394, directory = tempdir(), release = release_id)

unzip(y, list = TRUE)

# Overwrite existing files if needed
z <- download_item(394, directory = tempdir(), overwrite = TRUE)

# An informative error is raised if your API key is invalid or missing
try(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 metadata pertaining to the specified NHS TRUD item. Use the item numbers from trud_items() or get_subscribed_metadata().

Subscription Required

You must subscribe to TRUD items individually through the NHS TRUD website before you can access them using get_item_metadata() or download_item(). Simply having an API key is not sufficient. To see items you're already subscribed to, use get_subscribed_metadata(). To browse all available items, use trud_items().

Usage

get_item_metadata(item, release_scope = c("all", "latest"))

Arguments

item

An integer, the item to be downloaded. Get these from trud_items() or get_subscribed_metadata().

release_scope

Which releases to retrieve metadata for. Use "all" to get all releases, or "latest" to get only the most recent release.

Value

A list containing item metadata, including release information that can be used with download_item(). Release IDs for specific downloads are in the id field of each release.

See Also

Examples


# Get metadata for Community Services Data Set pre-deadline extract XML Schema
get_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 missing
try(withr::with_envvar(c("TRUD_API_KEY" = ""), get_item_metadata(394)))

Get metadata for subscribed NHS TRUD items

Description

A convenience wrapper around trud_items() and get_item_metadata(), retrieving metadata for only items that the user is subscribed to. This is particularly useful for seeing what data you can download with download_item(). If you need access to additional items, browse available options with trud_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 "all" to get all releases, or "latest" to get only the most recent release.

Value

A tibble, with item metadata stored in the list column metadata. Use the item_number column values with download_item().

See Also

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

Scrapes this page from the NHS TRUD website for all available items. The item_number column in the result contains the identifiers you need for get_item_metadata() and download_item().

Subscription Required

You must subscribe to TRUD items individually through the NHS TRUD website before you can access them using get_item_metadata() or download_item(). Simply having an API key is not sufficient. To see items you're already subscribed to, use get_subscribed_metadata(). To browse all available items, use trud_items().

Usage

trud_items()

Value

A tibble, with columns item_number and item_name. Use the item_number values as arguments to get_item_metadata() and download_item().

See Also

Examples


trud_items()