A Python client for the Office of National Statistics (ONS) API.
onspy provides a simple interface to access data from the UK Office of National Statistics API.
It allows you to:
- Retrieve datasets and their metadata
- Search for specific data within datasets
- Browse code lists and dimensions
- Access quality and methodology information
pip install onspyimport onspy
# List all available datasets
datasets = onspy.ons_datasets()
print(datasets.head())
# Get a list of dataset IDs
ids = onspy.ons_ids()
print(ids[:5])
# View dataset information
onspy.ons_desc("cpih01")
# Download the latest version of a dataset
df = onspy.ons_get_latest("cpih01")
print(df.head())
# Get specific observations
obs = onspy.ons_get_obs("cpih01", geography="K02000001", aggregate="cpih1dim1A0", time="*")
print(obs.head())The examples folder contains examples demonstrating basic usage and more advanced usage, such as creating plots from datasets:
ons_datasets()- Get information about all available datasetsons_ids()- Get a list of all available dataset IDsons_desc(id)- Print a description of a datasetons_editions(id)- Get available editions for a datasetons_latest_edition(id)- Get the latest edition name for a datasetons_latest_version(id)- Get the latest version number for a dataset
ons_get(id, edition=None, version=None)- Download a datasetons_get_latest(id)- Download the latest version of a dataset across all editionsons_get_obs(id, edition=None, version=None, **kwargs)- Get specific observationsons_dim(id, edition=None, version=None)- Get dimensions for a datasetons_dim_opts(id, dimension, edition=None, version=None)- Get dimension optionsons_meta(id, edition=None, version=None)- Get metadata for a dataset
ons_codelists()- Get a list of all available code listsons_codelist(code_id)- Get details for a specific code listons_codelist_editions(code_id)- Get editions for a code listons_codes(code_id, edition)- Get codes for a specific edition of a code listons_code(code_id, edition, code)- Get details for a specific code
ons_search(id, name, query, edition=None, version=None)- Search for a dataset
ons_browse()- Open the ONS developer webpage in a browserons_browse_qmi(id)- Open the QMI webpage for a dataset in a browser
# Get an older version of a dataset
df = onspy.ons_get(id="cpih01", version="5")# Get dimensions for a dataset
dimensions = onspy.ons_dim("cpih01")
print(dimensions)
# Get options for a specific dimension
time_options = onspy.ons_dim_opts("cpih01", dimension="time")
print(time_options[:5])
# Get observations with specific dimension filters
obs = onspy.ons_get_obs(
"cpih01",
geography="K02000001", # UK
aggregate="cpih1dim1A0", # All items
time="Oct-11" # Specific time
)
print(obs)# Get all code lists
code_lists = onspy.ons_codelists()
print(code_lists[:5])
# Get details for a specific code list
quarter_cl = onspy.ons_codelist("quarter")
print(quarter_cl)
# Get editions for a code list
editions = onspy.ons_codelist_editions("quarter")
print(editions)
# Get codes for an edition
codes = onspy.ons_codes("quarter", "one-off")
print(codes)If you are building a bot using onspy, it is best practice to update the User-Agent header in client.py.
The API is rate limited. Ensure your bot respects the limits to avoid being blocked.
For detailed API documentation, please refer to the ONS Developer Hub.
Copyright (C) 2025 Joe Wait
This program is free software: you can redistribute it and/or modify it under the terms of the GPL-3.0 License - see the LICENSE file for details.
Contributions are welcomed! Please feel free to raise an Issue or submit a Pull Request.
This project was inspired by onsr by Kostas Vasilopoulos.