Report whether the server holds a NOMIS API key, and test the cell limit.

Without a key, every data request is silently capped at 25,000 records: NOMIS answers with HTTP 200 and a truncated body, no error. With a valid unique ID the cap is lifted.

Run this when a fetch reports truncation, or to confirm setup. The probe downloads one narrow column of a large query, so it takes a few seconds.

To obtain a key: sign in at nomisweb.co.uk, open My Account, and copy the unique ID (it starts with 0x). Supply it to this server as the NOMIS_UID environment variable, or point NOMIS_CONFIG_FILE at a YAML file with nomis: {uid: 0x...}. The key is a password: it is never exposed as a tool parameter and is redacted from every URL returned here.

Find NOMIS datasets by keyword. Start here, then call get_dataset_dimensions.

Returns dataset ids such as NM_1_1 along with name, description, keywords and status. Prefer datasets whose status is "Current (being actively updated)" over "Historical (not actively being updated)" unless the user asked for a historical series.

NOMIS publishes over 1,600 datasets, so a narrow term is better than a broad one. Census topic summary tables are named with a TS prefix, e.g. searching 'TS058' finds the travel-to-work table.

List the dimensions a dataset accepts as filters, and its geography types.

Essential before fetching. Dimensions vary per dataset: across NOMIS there are over 480 distinct dimension concepts, and only 'measures', 'freq' and 'geography' are near-universal. A filter this tool does not list will be rejected or silently ignored by fetch_data.

The returned 'geography_types' are the vintages available for this dataset, e.g. TYPE424 (local authorities as of April 2023) or TYPE151 (2021 LSOAs). Pick one, then pass it to search_codes to resolve an area name to a code.

Resolve dimension values to the numeric codes fetch_data needs.

Codes are opaque integers (Bristol, City of is 1778384919 in TYPE424) and cannot be guessed or derived from ONS GSS codes. Always come here first.

Geography needs two steps. Searching geography without a type_code returns the list of geography types for the dataset, because the top of the geography codelist holds only a handful of country nodes and a search there matches nothing and returns success. Pick a type, then search within it:

search_codes('NM_1_1', 'geography')                     -> type list
search_codes('NM_1_1', 'geography', 'bristol', 'TYPE424')
    -> value 1778384919, geog_code E06000023

Non-geography dimensions are searched directly, no type_code needed.

Fetch observations from a dataset. Codes must come from search_codes.

Returns rows plus 'total', the number of records matching the query, and 'truncated'. Read them. NOMIS answers an oversized query with HTTP 200 and a body cut short with no error, so a result can look complete while holding a small fraction of the data. Never total, average or rank a truncated result; narrow the filters, or use fetch_data_to_file.

A worked example, claimant count for Bristol in the latest month:

fetch_data('NM_1_1', {'geography': '1778384919', 'sex': '7',
                      'item': '1', 'measures': '20100',
                      'time': 'latest'})

Requesting a whole geography type (e.g. 'TYPE151' for 2021 LSOAs) across several dimensions produces millions of records. Use fetch_data_to_file.

Stream an unrestricted query to a CSV file instead of into the reply.

For results too large to read: whole geography types, long time series, LSOA-level census tables. Nothing is loaded into memory or context, so use this rather than paging fetch_data hundreds of times.

Without an API key the file is still capped at 25,000 records; run check_auth first if the row count looks suspiciously round.

Returns the path for onward analysis in R, DuckDB or pandas.