README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# trud <a href="https://rmgpanw.github.io/trud/"><img src="man/figures/logo.png" align="right" height="138"/></a>

<!-- badges: start -->
[![pkgdown](https://github.com/rmgpanw/trud/actions/workflows/pkgdown.yaml/badge.svg)](https://github.com/rmgpanw/trud/actions/workflows/pkgdown.yaml) [![Codecov test coverage](https://codecov.io/gh/rmgpanw/trud/branch/main/graph/badge.svg)](https://app.codecov.io/gh/rmgpanw/trud?branch=main)
[![R-CMD-check](https://github.com/rmgpanw/trud/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/rmgpanw/trud/actions/workflows/R-CMD-check.yaml)
[![CRAN status](https://www.r-pkg.org/badges/version/trud)](https://CRAN.R-project.org/package=trud)
[![](https://cranlogs.r-pkg.org/badges/last-month/trud)](https://cran.r-project.org/package=trud)
<!-- badges: end -->

The goal of `trud` is to provide a convenient R interface to the [NHS TRUD API](https://isd.digital.nhs.uk/trud/users/guest/filters/0/api).

## Installation

You can install this package from CRAN:

``` r
install.packages("trud")
```

Or you can install the development version  of `trud` from [GitHub](https://github.com/rmgpanw/trud) with:

``` r
# install.packages("devtools")
devtools::install_github("rmgpanw/trud")
```

You will also need to:

-   [Sign up for an account](https://isd.digital.nhs.uk/trud/users/guest/filters/0/account/form) with NHS TRUD
-   Set your API key (shown on your account information page) as an environmental variable named `TRUD_API_KEY`. The best way to do this is by placing your API key in a [`.Renviron` file](https://rstats.wtf/r-startup.html#renviron).

## Examples

Retrieve available endpoints[^1]:

[^1]: Item numbers can also be found in the URLs of releases pages, between `items` and `releases`. For example, the URL for the [Community Services Data Set pre-deadline extract XML Schema](https://isd.digital.nhs.uk/trud/users/guest/filters/0/categories/1/items/394/releases) releases page is `https://isd.digital.nhs.uk/trud/users/guest/filters/0/categories/1/items/394/releases` and the item number is `394`.

```{r trud-items}
library(trud)

trud_items()
```

Get metadata for an item:

```{r get-item-metadata}
get_item_metadata(394) |>
  purrr::map_at("releases", \(release) purrr::map(release, names))
```

Get metadata for all subscribed items:

```{r get-subscribed_metadata}
get_subscribed_metadata()
```

Download an item:

```{r download-item}
# by default the latest release will be downloaded to the current working directory
x <- download_item(394, directory = tempdir())
unzip(x, list = TRUE)
```