Title: Query the 'NHS TRUD API'
Version: 0.1.0
Description: A convenient R interface to the 'National Health Service (NHS) Technology Reference Update Distribution (TRUD) API'. Retrieve available releases for items that you are subscribed to and download these with ease. 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.2.3
Imports: cli, dplyr, httr2, magrittr, purrr, rlang, rvest, stringr, tibble, tidyselect
URL: https://rmgpanw.github.io/trud/, https://github.com/rmgpanw/trud
BugReports: https://github.com/rmgpanw/trud/issues
Suggests: testthat (≥ 3.0.0), withr
Config/testthat/edition: 3
NeedsCompilation: no
Packaged: 2024-07-21 14:30:14 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]
Maintainer: Alasdair Warwick <alasdair.warwick.19@ucl.ac.uk>
Repository: CRAN
Date/Publication: 2024-07-23 00:20:02 UTC

trud: Query the 'NHS TRUD API'

Description

logo

A convenient R interface to the 'National Health Service (NHS) Technology Reference Update Distribution (TRUD) API'. Retrieve available releases for items that you are subscribed to and download these with ease. 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:

See Also

Useful links:

Pipe operator

Description

See magrittr::%>% for details.

Usage

lhs %>% rhs

Arguments

lhs

A value or the magrittr placeholder.

rhs

A function call using the magrittr semantics.

Value

The result of calling rhs(lhs).

Download NHS TRUD item

Description

Downloads files for a specified NHS TRUD item (requires a subscription). By default this is the latest release.

Usage

download_item(
  item,
  directory = ".",
  download_file = "archive",
  TRUD_API_KEY = NULL,
  release = NULL
)

Arguments

item

An integer, the item to be downloaded.

directory

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

download_file

The item file to be downloaded. Valid values:

  • "archive" (the release item)

  • "checksum"

  • "signature"

  • "publickKey"

TRUD_API_KEY

A string. The name of an environmental variable containing your TRUD API key. If NULL (default) this is assumed to be called TRUD_API_KEY.

release

The name of a specific release ID to be downloaded (this can be ascertained using get_item_metadata()). If NULL (default), then the latest item release will be downloaded.

Value

The file path to the downloaded file, returned invisibly.

Examples

## Not run: 
 # 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
 release <- get_item_metadata(394)$releases[[2]]$id

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

 unzip(y, list = TRUE)

## End(Not run)

# An informative error is raised if your API key is invalid or missing
try(download_item(394, TRUD_API_KEY = "INVALID_API_KEY"))

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.

Usage

get_item_metadata(item, TRUD_API_KEY = NULL, latest_only = FALSE)

Arguments

item

An integer, the item to be downloaded.

TRUD_API_KEY

A string. The name of an environmental variable containing your TRUD API key. If NULL (default) this is assumed to be called TRUD_API_KEY.

latest_only

If TRUE, only metadata pertaining to the latest item release will be retrieved. By default this is set to FALSE.

Value

A list.

Examples

## Not run: 
 # Get metadata for Community Services Data Set pre-deadline extract XML Schema
 get_item_metadata(394) |>
   purrr::map_at("releases", \(release) purrr::map(release, names))

# Include metadata for any previous releases using `latest_only = FALSE`
get_item_metadata(394, latest_only = FALSE) |>
   purrr::map_at("releases", \(release) purrr::map(release, names))

## End(Not run)

# An informative error is raised if your API key is invalid or missing
try(download_item(394, TRUD_API_KEY = "INVALID_API_KEY"))

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.

Usage

get_subscribed_metadata(TRUD_API_KEY = NULL, latest_only = FALSE)

Arguments

TRUD_API_KEY

A string. The name of an environmental variable containing your TRUD API key. If NULL (default) this is assumed to be called TRUD_API_KEY.

latest_only

If TRUE, only metadata pertaining to the latest item release will be retrieved. By default this is set to FALSE.

Value

A tibble, with item metadata stored in the list column metadata.

See Also

trud_items(), get_item_metadata()

Examples

## Not run: 
get_subscribed_metadata()

## End(Not run)

Get available NHS TRUD items

Description

Scrapes this page from the NHS TRUD website for all available items.

Usage

trud_items()

Value

A tibble, with columns item_number and item_name.

Examples

## Not run: 
 trud_items()

## End(Not run)