statswales_get_dataset: Retrieve data for a dataset

In statswalesr: Easily Extract Data from 'StatsWales'

Retrieve data for a dataset

Description

Returns a data frame containing rows from a published dataset. Filters and display options are submitted to the API as a stored query; the same inputs always produce the same query ID so repeated calls are efficient.

Usage

statswales_get_dataset(
  dataset_id,
  lang = "en-gb",
  page_number = 1,
  page_size = 10000,
  filter = NULL,
  options = list(use_raw_column_names = FALSE, use_reference_values = FALSE,
    data_value_type = "formatted"),
  sort_by = NULL,
  all_pages = TRUE,
  tidy = TRUE
)

Arguments

dataset_id	A dataset UUID string. Use statswales_list_datasets() to find dataset IDs.
lang	Language for text values. One of "en-gb" (default), "en", "cy-gb", or "cy".
page_number	Page of results to return. Default 1. Only used when all_pages = FALSE.
page_size	Rows per page. Default 10000 (the API maximum).
filter	A list of filter objects. Each element is a named list mapping a column name (from statswales_get_filters()) to a character vector of reference codes. Multiple list elements use AND logic; multiple codes within one element use OR logic. Example: list(list(Year = c("2020", "2021")), list(Area = c("W92000004"))).
options	A named list of display options: use_raw_column_names FALSE (default) returns human-readable column names; TRUE returns internal fact-table names. use_reference_values FALSE (default) returns human-readable values; TRUE returns reference codes. data_value_type One of "raw", "raw_extended", "formatted" (default), "formatted_extended", or "with_note_codes". Note: as of July 2026 the StatsWales API ignores use_raw_column_names and use_reference_values, so output always uses human-readable column names and values regardless of these settings. Only data_value_type currently changes the output.
sort_by	Optional sort order. Either a ready-made string in the API's "column:direction" format (e.g. "Year:desc"), or a named character vector such as c(Year = "desc", Area = "asc"). Directions are "asc" or "desc".
all_pages	If TRUE (default), automatically fetches and row-binds all pages so the entire dataset is returned. Set to FALSE to retrieve a single page controlled by page_number and page_size.
tidy	If TRUE (default), the result is cleaned for analysis: the API's internal ⁠*_sort⁠ columns are dropped, whitespace padding is stripped, and numeric-looking columns (such as the data values) are converted to numeric. Set to FALSE to return the API response as-is.

Value

A data frame of dataset rows, or NULL if the request fails.

Examples

## Not run: 
datasets <- statswales_list_datasets()
id <- datasets$id[1]

# Entire dataset, human-readable (default)
df <- statswales_get_dataset(id)

# A single page of 100 rows
df_page <- statswales_get_dataset(id, all_pages = FALSE, page_size = 100)

# Filtered to specific years
filters <- statswales_get_filters(id)
df_filtered <- statswales_get_dataset(
  id,
  filter = list(list(Year = c("2020", "2021")))
)

## End(Not run)

statswalesr documentation built on July 12, 2026, 5:06 p.m.