Package 'ons'

Title: Download Data from the 'Office for National Statistics'
Description: Provides functions to download and tidy statistical data published by the 'Office for National Statistics' <https://www.ons.gov.uk>. Covers GDP, inflation (CPI, CPIH, RPI), unemployment, employment, wages, trade, retail sales, house prices, productivity, population, and public sector finances. Most series are fetched from the 'ONS' website using its CSV time series endpoint. House price data is sourced from 'HM Land Registry' <https://www.gov.uk/government/organisations/land-registry>. Data is cached locally between sessions.
Authors: Charles Coverdale [aut, cre]
Maintainer: Charles Coverdale <[email protected]>
License: MIT + file LICENSE
Version: 0.1.4
Built: 2026-06-03 06:42:02 UTC
Source: https://github.com/charlescoverdale/ons

Help Index

ons: Download Data from the 'Office for National Statistics'

Description

Provides functions to download and tidy statistical data published by the 'Office for National Statistics' https://www.ons.gov.uk. Covers GDP, inflation (CPI, CPIH, RPI), unemployment, employment, wages, trade, retail sales, house prices, productivity, population, and public sector finances. Most series are fetched from the 'ONS' website using its CSV time series endpoint. House price data is sourced from 'HM Land Registry' https://www.gov.uk/government/organisations/land-registry. Data is cached locally between sessions.

Author(s)

Maintainer: Charles Coverdale [email protected]

See Also

Useful links:

Clear the local download cache

Description

Removes cached data files stored by this package. By default all cached files are deleted. Use max_age_days to remove only files older than a given number of days.

Usage

clear_cache(max_age_days = NULL)

Arguments

max_age_days

Numeric. If supplied, only files older than this many days are removed. If NULL (the default), all cached files are removed.

Value

Invisibly returns NULL. Called for its side effect of deleting cached files.

See Also

Other data access: ons_get(), ons_search()

Examples

op <- options(ons.cache_dir = tempdir())
clear_cache()
options(op)

Download consumer price inflation

Description

Downloads CPI, CPIH, or RPI data from the ONS. Returns either the annual rate of change or the index level.

Usage

ons_cpi(
  measure = c("cpi", "cpih", "rpi"),
  type = c("rate", "index"),
  from = NULL,
  to = NULL,
  cache = TRUE
)

Arguments

measure

Character. One of "cpi" (default), "cpih", or "rpi".
type

Character. One of "rate" (default, annual percentage change) or "index" (index level).
from

Date or character (YYYY-MM-DD). Start date. Defaults to NULL (all available data).
to

Date or character (YYYY-MM-DD). End date. Defaults to NULL.
cache

Logical. Use cached data if available (default TRUE).

Value

A data frame with columns:

date

Date. First day of the month.

value

Numeric. Inflation rate (percent) or index level.

Source

https://www.ons.gov.uk

See Also

Other economic indicators: ons_gdp(), ons_monthly_gdp(), ons_population(), ons_productivity()

Examples

op <- options(ons.cache_dir = tempdir())
try(ons_cpi(from = "2020-01-01"))
options(op)

Download employment rate

Description

Downloads the UK employment rate (aged 16 to 64, seasonally adjusted) from the ONS Labour Market Statistics. Available from 1971.

Usage

ons_employment(
  group = c("total", "male", "female"),
  from = NULL,
  to = NULL,
  cache = TRUE
)

Arguments

group

Character. One of "total" (default), "male", or "female".
from

Date or character (YYYY-MM-DD). Start date. Defaults to NULL (all available data).
to

Date or character (YYYY-MM-DD). End date. Defaults to NULL.
cache

Logical. Use cached data if available (default TRUE).

Value

A data frame with columns:

date

Date. First day of the period.

value

Numeric. Employment rate (percent).

Source

https://www.ons.gov.uk

See Also

Other labour market: ons_inactivity(), ons_unemployment(), ons_wages()

Examples

op <- options(ons.cache_dir = tempdir())
try(ons_employment(from = "2020-01-01"))
options(op)

Download GDP data

Description

Downloads quarterly Gross Domestic Product data from the ONS. Available from 1948 (levels) or 1955 (growth rates).

Usage

ons_gdp(
  measure = c("growth", "yoy", "level", "nominal"),
  from = NULL,
  to = NULL,
  cache = TRUE
)

Arguments

measure

Character. One of "growth" (default, quarter-on-quarter percentage change), "yoy" (year-on-year percentage change), "level" (chained volume measure in GBP millions, seasonally adjusted), or "nominal" (current price GBP millions, seasonally adjusted).
from

Date or character (YYYY-MM-DD). Start date. Defaults to NULL (all available data).
to

Date or character (YYYY-MM-DD). End date. Defaults to NULL.
cache

Logical. Use cached data if available (default TRUE).

Value

A data frame with columns:

date

Date. First day of the quarter.

value

Numeric. GDP value (percent for growth measures, GBP millions for level measures).

Source

https://www.ons.gov.uk

See Also

Other economic indicators: ons_cpi(), ons_monthly_gdp(), ons_population(), ons_productivity()

Examples

op <- options(ons.cache_dir = tempdir())
try(ons_gdp(from = "2020-01-01"))
options(op)

Download any ONS time series by CDID code

Description

Fetches a time series from the ONS website using its CDID (four-character series identifier). The function uses the ONS Search API to discover the download path, then retrieves the CSV.

Usage

ons_get(cdid, from = NULL, to = NULL, cache = TRUE)

Arguments

cdid

Character vector. One or more ONS CDID codes (e.g. "IHYQ" for quarterly GDP growth). Maximum 50 codes per call.
from

Date or character (YYYY-MM-DD). Start date filter. Defaults to NULL (all available data).
to

Date or character (YYYY-MM-DD). End date filter. Defaults to NULL (up to the latest observation).
cache

Logical. Use cached data if available (default TRUE).

Details

CDID codes can be found by browsing the ONS time series explorer at https://www.ons.gov.uk/timeseriestool or by using ons_search().

Value

A data frame with columns:

date

Date. Observation date (first day of the period).

cdid

Character. The CDID code.

value

Numeric. Observation value.

Source

https://www.ons.gov.uk

See Also

Other data access: clear_cache(), ons_search()

Examples

op <- options(ons.cache_dir = tempdir())
try(ons_get("IHYQ", from = "2020-01-01"))
options(op)

Download UK house prices

Description

Downloads UK average house prices from the HM Land Registry UK House Price Index. Available from 1968. Data is jointly produced by the ONS and HM Land Registry.

Usage

ons_house_prices(from = NULL, to = NULL, cache = TRUE)

Arguments

from

Date or character (YYYY-MM-DD). Start date. Defaults to NULL (all available data).
to

Date or character (YYYY-MM-DD). End date. Defaults to NULL.
cache

Logical. Use cached data if available (default TRUE).

Details

The function automatically finds the latest available monthly file from HM Land Registry, working backwards from the current month.

Value

A data frame with columns:

date

Date. First day of the month.

average_price_gbp

Numeric. Average house price (GBP).

annual_change_pct

Numeric. Annual percentage change.

Source

https://www.gov.uk/government/collections/uk-house-price-index-reports

See Also

Other trade and prices: ons_retail_sales(), ons_trade()

Examples

op <- options(ons.cache_dir = tempdir())
try(ons_house_prices(from = "2020-01-01"))
options(op)

Download economic inactivity

Description

Downloads the number of economically inactive people (aged 16 to 64, seasonally adjusted) from the ONS Labour Market Statistics. Available from 1971.

Usage

ons_inactivity(from = NULL, to = NULL, cache = TRUE)

Arguments

from

Date or character (YYYY-MM-DD). Start date. Defaults to NULL (all available data).
to

Date or character (YYYY-MM-DD). End date. Defaults to NULL.
cache

Logical. Use cached data if available (default TRUE).

Value

A data frame with columns:

date

Date. First day of the period.

value

Numeric. Economically inactive people (thousands).

Source

https://www.ons.gov.uk

See Also

Other labour market: ons_employment(), ons_unemployment(), ons_wages()

Examples

op <- options(ons.cache_dir = tempdir())
try(ons_inactivity(from = "2020-01-01"))
options(op)

Download monthly GDP estimate

Description

Downloads the monthly estimate of GDP from the ONS. This is an experimental index-based estimate, available from 1997.

Usage

ons_monthly_gdp(from = NULL, to = NULL, cache = TRUE)

Arguments

from

Date or character (YYYY-MM-DD). Start date. Defaults to NULL (all available data).
to

Date or character (YYYY-MM-DD). End date. Defaults to NULL.
cache

Logical. Use cached data if available (default TRUE).

Value

A data frame with columns:

date

Date. First day of the month.

value

Numeric. Monthly GDP index (2019 = 100).

Source

https://www.ons.gov.uk

See Also

Other economic indicators: ons_cpi(), ons_gdp(), ons_population(), ons_productivity()

Examples

op <- options(ons.cache_dir = tempdir())
try(ons_monthly_gdp(from = "2020-01-01"))
options(op)

Download population estimates

Description

Downloads mid-year population estimates for the United Kingdom from the ONS. Returns annual estimates.

Usage

ons_population(from = NULL, to = NULL, cache = TRUE)

Arguments

from

Date or character (YYYY-MM-DD). Start date. Defaults to NULL (all available data).
to

Date or character (YYYY-MM-DD). End date. Defaults to NULL.
cache

Logical. Use cached data if available (default TRUE).

Value

A data frame with columns:

date

Date. Mid-year date (represented as 1 January).

value

Numeric. Population estimate (thousands).

Source

https://www.ons.gov.uk

See Also

Other economic indicators: ons_cpi(), ons_gdp(), ons_monthly_gdp(), ons_productivity()

Examples

op <- options(ons.cache_dir = tempdir())
try(ons_population(from = "2000-01-01"))
options(op)

Download labour productivity

Description

Downloads quarterly labour productivity data from the ONS. Available as output per hour worked or output per worker.

Usage

ons_productivity(
  measure = c("per_hour", "per_worker"),
  from = NULL,
  to = NULL,
  cache = TRUE
)

Arguments

measure

Character. One of "per_hour" (default, output per hour worked) or "per_worker" (output per worker). Both are seasonally adjusted indices.
from

Date or character (YYYY-MM-DD). Start date. Defaults to NULL (all available data).
to

Date or character (YYYY-MM-DD). End date. Defaults to NULL.
cache

Logical. Use cached data if available (default TRUE).

Value

A data frame with columns:

date

Date. First day of the quarter.

value

Numeric. Productivity index.

Source

https://www.ons.gov.uk

See Also

Other economic indicators: ons_cpi(), ons_gdp(), ons_monthly_gdp(), ons_population()

Examples

op <- options(ons.cache_dir = tempdir())
try(ons_productivity(from = "2020-01-01"))
options(op)

Download public sector finances

Description

Downloads public sector net borrowing (excluding public sector banks) from the ONS. Available from 1993.

Usage

ons_public_finances(from = NULL, to = NULL, cache = TRUE)

Arguments

from

Date or character (YYYY-MM-DD). Start date. Defaults to NULL (all available data).
to

Date or character (YYYY-MM-DD). End date. Defaults to NULL.
cache

Logical. Use cached data if available (default TRUE).

Value

A data frame with columns:

date

Date. First day of the month.

value

Numeric. Public sector net borrowing (GBP millions).

Source

https://www.ons.gov.uk

Examples

op <- options(ons.cache_dir = tempdir())
try(ons_public_finances(from = "2020-01-01"))
options(op)

Download retail sales index

Description

Downloads the Retail Sales Index from the ONS. Returns volume (quantity) or value (amount spent) indices.

Usage

ons_retail_sales(
  type = c("volume", "value"),
  from = NULL,
  to = NULL,
  cache = TRUE
)

Arguments

type

Character. One of "volume" (default, quantity bought, seasonally adjusted) or "value" (amount spent, not seasonally adjusted).
from

Date or character (YYYY-MM-DD). Start date. Defaults to NULL (all available data).
to

Date or character (YYYY-MM-DD). End date. Defaults to NULL.
cache

Logical. Use cached data if available (default TRUE).

Value

A data frame with columns:

date

Date. First day of the month.

value

Numeric. Retail sales index.

Source

https://www.ons.gov.uk

See Also

Other trade and prices: ons_house_prices(), ons_trade()

Examples

op <- options(ons.cache_dir = tempdir())
try(ons_retail_sales(from = "2020-01-01"))
options(op)

Search for ONS time series

Description

Searches the ONS catalogue for time series matching a keyword or phrase. Returns CDID codes, titles, and dataset information that can be used with ons_get().

Usage

ons_search(query, limit = 10L)

Arguments

query

Character. Search term (e.g. "GDP growth", "unemployment").
limit

Integer. Maximum number of results to return (default 10, maximum 50).

Value

A data frame with columns:

cdid

Character. The four-character CDID code.

dataset_id

Character. The ONS dataset identifier.

title

Character. Description of the series.

release_date

Character. Date of the most recent release.

Source

https://www.ons.gov.uk

See Also

Other data access: clear_cache(), ons_get()

Examples

op <- options(ons.cache_dir = tempdir())
try(ons_search("GDP growth"))
options(op)

Download UK trade data

Description

Downloads UK trade in goods and services data from the ONS. Available from 1948.

Usage

ons_trade(
  measure = c("balance", "exports", "imports"),
  from = NULL,
  to = NULL,
  cache = TRUE
)

Arguments

measure

Character. One of "balance" (default, trade balance), "exports" (total exports), or "imports" (total imports). All in GBP millions, current prices, seasonally adjusted.
from

Date or character (YYYY-MM-DD). Start date. Defaults to NULL (all available data).
to

Date or character (YYYY-MM-DD). End date. Defaults to NULL.
cache

Logical. Use cached data if available (default TRUE).

Value

A data frame with columns:

date

Date. First day of the month.

value

Numeric. Trade value (GBP millions).

Source

https://www.ons.gov.uk

See Also

Other trade and prices: ons_house_prices(), ons_retail_sales()

Examples

op <- options(ons.cache_dir = tempdir())
try(ons_trade(from = "2020-01-01"))
options(op)

Download unemployment rate

Description

Downloads the UK unemployment rate (aged 16 and over, seasonally adjusted) from the ONS Labour Market Statistics. Available from 1971.

Usage

ons_unemployment(from = NULL, to = NULL, cache = TRUE)

Arguments

from

Date or character (YYYY-MM-DD). Start date. Defaults to NULL (all available data).
to

Date or character (YYYY-MM-DD). End date. Defaults to NULL.
cache

Logical. Use cached data if available (default TRUE).

Value

A data frame with columns:

date

Date. First day of the period.

value

Numeric. Unemployment rate (percent).

Source

https://www.ons.gov.uk

See Also

Other labour market: ons_employment(), ons_inactivity(), ons_wages()

Examples

op <- options(ons.cache_dir = tempdir())
try(ons_unemployment(from = "2020-01-01"))
options(op)

Download average weekly earnings

Description

Downloads average weekly earnings (AWE) for the whole economy from the ONS Labour Market Statistics. Available from 2000.

Usage

ons_wages(
  measure = c("level", "growth", "real"),
  from = NULL,
  to = NULL,
  cache = TRUE
)

Arguments

measure

Character. One of "level" (default, GBP per week), "growth" (year-on-year 3-month average percentage change), or "real" (real terms index, seasonally adjusted regular pay).
from

Date or character (YYYY-MM-DD). Start date. Defaults to NULL (all available data).
to

Date or character (YYYY-MM-DD). End date. Defaults to NULL.
cache

Logical. Use cached data if available (default TRUE).

Value

A data frame with columns:

date

Date. First day of the month.

value

Numeric. Earnings level (GBP), growth rate (percent), or real index.

Source

https://www.ons.gov.uk

See Also

Other labour market: ons_employment(), ons_inactivity(), ons_unemployment()

Examples

op <- options(ons.cache_dir = tempdir())
try(ons_wages(from = "2020-01-01"))
options(op)