Get a single dataset's metadata and its latest edition/version.

Follows the dataset's latest_version link so you get the concrete edition and version numbers needed by the downstream tools, plus the available download formats (csv, xlsx) for the whole dataset.

List the dimensions (variables) of a dataset version.

Every dataset has time and geography; the rest are topic dimensions. number_of_options tells you how many codes each holds. Feed a dimension name into get_options to see valid codes.

Get full metadata for a dataset version (provenance, downloads).

Includes the CSV/XLSX/CSVW download hrefs for the complete version, dimension descriptions, release date and usage notes. Use this when bulk download is more sensible than per-observation queries.

Retrieve observation(s) for a dataset version.

Supply exactly one option code per dimension in dimensions, e.g. {"time": "Mar-18", "geography": "K02000001", "aggregate": "cpih1dim1A0"}. One (and only one) dimension may be the wildcard "*" to return every value along that axis — useful for pulling a whole time series in a single call.

Returns the observations plus the unit of measure.

List valid option codes for one dimension of a dataset version.

Each option has an option code (what you pass to get_observations) and a human label. Dimensions can be large (e.g. thousands of geographies or hundreds of time periods), so page with offset/limit.

Full detail for one release-calendar entry by its uri.

uri is the release path (e.g. "/releases/consumerpriceinflationjuly2026"), as returned by list_releases. Gives the definitive release date and whether it is confirmed (finalised) or still provisional, any cancellation notice, the publishing contact, and links to the datasets and documents the release will contain — the reliable answer for a real next-release date.

Get a PUBLISHED ONS time series by its website URI. PREFER THIS for headline indicators (inflation rates, unemployment rate, GDP growth).

This hits /v1/data, which serves the same figures as the ONS website — the published headline value, not something derived from an index. It returns months/quarters/years already in chronological order, so the last element is the latest period.

uri is the ONS website path for the series, e.g. "/economy/inflationandpriceindices/timeseries/l55o/mm23" for the CPIH annual rate. These URIs are evergreen and don't change between releases. Find them via the series CDID (l55o, d7g7, mgsx ...) and the dataset (mm23, lms ...).

Prefer this over get_observations for "what is the latest X rate" questions: the CMD datasets behind get_observations are curated separately and some lag the published series by months or years.

CAVEAT on next_release: it is a snapshot captured at the LAST publication, not a live release-calendar lookup, so it can be wrong. Observed reporting "15 July" when the ONS release calendar said "22 July". Treat it as indicative only; for a real next-release date use list_releases / get_release (the live calendar), not this field.

List the content published under a topic (bulletins, articles, key time series, dataset pages).

topic_id is the numeric id from list_topics (e.g. "4972" = Inflation and price indices). Items carry a type and title; where an item is a published time series, timeseries_uri is filled in ready to pass straight to get_timeseries. A convenient bridge from a topic to the headline series under it.

List available ONS datasets (paginated).

Returns id, title, description, release_frequency and the latest edition/version links for each dataset. Use offset to page through the full catalogue (there are several hundred datasets).

Browse the ONS release calendar — the AUTHORITATIVE schedule of statistical publications. USE THIS to answer "when is the next X released", not the next_release field on get_timeseries/get_dataset (which is a snapshot from the last publication and can be wrong).

status is one of: "upcoming" (provisional + confirmed, not yet out — the default), "published" (already released), "cancelled". query filters by title/summary (e.g. "inflation", "GDP"). sort defaults to soonest-first for upcoming and most-recent-first otherwise; override with "release_date_asc" / "release_date_desc" / "title_asc".

Each item carries the release uri (pass to get_release for detail), title, summary, the ISO release_date, and a status of confirmed / provisional / cancelled. Dates that are still provisional may move — get_release shows whether a date is finalised.

Browse the ONS topic hierarchy (a taxonomy over the whole catalogue).

Call with no argument for the top-level topics (Economy, Employment and labour market, Business industry and trade, People population and community, Census ...). Pass a topic id (numeric, e.g. "1245" = Economy) as parent_id to list its subtopics. Each item reports whether it has_subtopics (drill down again) and has_content (list its publications with get_topic_content).

Build a direct Nomis download URL for bulk retrieval.

For large pulls it's often better to hand back a URL than to stream every observation through the model. Returns a ready-to-use link in the requested format (csv, xls, data.json). Nomis time and list syntax is supported in dimensions values.

List valid codes for one dimension of a Nomis dataset.

dimension is the conceptref from nomis_get_dataset (e.g. sex, age, measures, item). Each option has a Nomis value (the code you pass to nomis_get_data) and a human name. Optional search filters options by substring — useful for large codelists.

For geography specifically, prefer nomis_geography_search, which also lets you restrict by area type.

Resolve a place name to Nomis geography code(s) for a dataset.

Nomis geography codes are internal integers, not ONS mnemonics, and differ per dataset. Pass a place name (e.g. "Birmingham", "Wales") and get back matching {value, name} pairs to use as the geography param in nomis_get_data. Supports Nomis '*' wildcards.

Retrieve observations from a Nomis dataset (simple JSON).

dimensions maps conceptref -> code(s), e.g. {"geography": "2038432081", "sex": "5,6,7", "time": "latest", "measures": "20100"}. Values may be comma-separated lists or Nomis time syntax such as "latest" or "latestMINUS12-latest". measures is usually required (20100 = value).

Returns flat records with named dimension values and the numeric obs_value, plus the record count. Use nomis_get_dataset and nomis_dimension_options / nomis_geography_search first to find the right codes.

Get one Nomis dataset's overview and its dimensions.

dataset_id is a Nomis table id like NM_1_1 (Claimant Count) or NM_2021_1. Returns name, description and the dimensions, each with its conceptref — the parameter name to use in nomis_get_data. Every dataset has at least a geography and a time dimension.

Search Nomis census / labour-market datasets by keyword.

Matches query (case-insensitive substring) against dataset id, name and description across the whole Nomis catalogue. Returns each dataset's id (e.g. NM_1_1), name, description and the list of its dimensions with the conceptref you pass as a query param to nomis_get_data. Nomis covers Claimant Count, APS, Census 2011/2021 tables, workforce jobs and more — data the ONS beta API lacks.

Find datasets whose title, description or keywords match query.

The beta API has no server-side search, so this pages through the catalogue and filters client-side on a case-insensitive substring. Good for turning a topic ("inflation", "life expectancy") into a dataset id.