Easily Extract Data from 'StatsWales'

Download data from the 'StatsWales' public API (< https://api.stats.gov.wales/v2>) into R. Provides functions to list, search, and browse datasets by topic, retrieve data with optional filtering, sorting, and pivoting, and download datasets as CSV or Excel files.

statswalesr

statswalesr is an R package for accessing data from the StatsWales public API v2.

Installation

install.packages("statswalesr")

Usage

Discover datasets

library(statswalesr)

# List all published datasets (the full catalogue is fetched automatically)
datasets <- statswales_list_datasets()

# Full-text search
results <- statswales_search("hospital")
results_fuzzy <- statswales_search("transprt", mode = "fuzzy")

# Browse by topic
topics <- statswales_list_topics()
topic_content <- statswales_get_topic(topics$id[1])

Retrieve data

Dataset IDs are UUIDs returned by statswales_list_datasets() or statswales_search().

id <- datasets$id[1]

# Entire dataset, human-readable column names and values (default)
df <- statswales_get_dataset(id)

# A single page of rows, if you don't want everything
df_page <- statswales_get_dataset(id, all_pages = FALSE, page_size = 100)

# Welsh language
df_cy <- statswales_get_dataset(id, lang = "cy-gb")

Results are tidied for analysis by default: the API's internal *_sort columns are dropped, whitespace padding is stripped, and numeric columns (including the data values) are converted to numbers. Pass tidy = FALSE to get the API response as-is.

Filter data

The filter argument is a list of named lists. Multiple list elements use AND logic; multiple values within one element use OR logic.

# See what dimensions can be filtered
filters <- statswales_get_filters(id)
filters[[1]]$columnName   # dimension name (use as the key)
filters[[1]]$values       # data frame of reference codes and labels

# Filter to specific values
df_filtered <- statswales_get_dataset(
  id,
  filter = list(
    list(Year = c("2022", "2023")),        # AND
    list(Area = c("W92000004"))             # AND
  )
)

Display options

By default the package returns human-readable column names and values. Override with the options argument:

df_raw <- statswales_get_dataset(
  id,
  options = list(
    use_raw_column_names = TRUE,   # internal fact-table column names
    use_reference_values = TRUE,   # reference codes instead of labels
    data_value_type = "raw"        # raw data values
  )
)

Note: as of July 2026 the StatsWales API ignores use_raw_column_names and use_reference_values — output always uses human-readable column names and values. Only data_value_type currently changes the output.

Pivot tables

filters <- statswales_get_filters(id)
pivot <- statswales_get_pivot(
  id,
  x = filters[[1]]$columnName,
  y = filters[[2]]$columnName
)

Dataset metadata

meta <- statswales_get_metadata(id)
meta$published_revision$metadata  # titles and summaries (both languages)
meta$published_revision$designation  # "official", "accredited", etc.

Reusable query IDs

The API stores query configurations with a deterministic 12-character ID. The same filter inputs always produce the same ID, making results shareable and reproducible.

# Create a stored query and inspect it
fid <- statswales_create_query(id, filter = list(list(Year = c("2023"))))
query_info <- statswales_get_query(id, fid)
query_info$totalLines  # total rows matching the query

Download a file

# Download as CSV
path <- statswales_download_dataset(id, format = "csv")
df <- read.csv(path)

# Download filtered data as Excel
statswales_download_dataset(
  id,
  format = "xlsx",
  filter = list(list(Year = c("2022", "2023"))),
  path = "my_data.xlsx"
)

Function reference

All functions accept a lang parameter: "en-gb" (default), "en", "cy-gb", or "cy".

Hex sticker by Lew Furber.