Package 'trud'

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

• trud_items() to find item numbers

• get_subscribed_metadata() to see items you can access

• get_item_metadata() to explore available releases before downloading

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

• trud_items() to find item numbers

• get_subscribed_metadata() to see items you can access

• download_item() to download files using this metadata

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

• trud_items() to browse all available items

• get_item_metadata() for detailed metadata on specific items

• download_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

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

• get_subscribed_metadata() to see only items you're subscribed to

• get_item_metadata() to get detailed information about a specific item

• download_item() to download files for a specific item

Examples

trud_items()

---