# ONS Discovery MCP

> UK ONS Discovery — Search 337+ Statistical Datasets gives your AI agent direct access to the full Office for National Statistics catalog. You search by keyword, browse metadata, validate filter variables using `get_dimension_options`, and execute flexible queries against any dataset ID. This handles all aspects of UK statistics—from housing prices to employment rates—in one place.

## Overview
- **Category:** data-analytics
- **Price:** Free
- **Tags:** statistics, dataset-catalog, metadata, data-discovery, open-data, query-engine

## Description

You're connecting your agent straight into the full Office for National Statistics catalog. Forget bouncing between different government sites or wading through dense PDF manuals; you handle every step—finding the data, validating the filters, and pulling the final numbers—all in one place.

**Discovering the Right Dataset:** You don't know what you need off the top of your head? Use `search_datasets` to run a quick search across 337+ datasets. Just drop keywords like 'housing' or 'population,' and it spits out relevant dataset IDs, titles, and descriptions. If you want to browse everything available without searching, `list_datasets` gives you paginated access to the whole catalog.

**Getting Full Details:** Once you have a promising ID, you gotta know exactly what that data is. You run `get_dataset_info` on the specific dataset ID; this retrieves all the detailed metadata for you, including methodology notes and every available edition of the data. This tool also shows you all the dimensions included in the set.

**Setting Up Filters:** Before you can pull anything, you gotta define your variables. You use `get_dimensions` to list every possible filter variable that dataset accepts—think 'geography' or 'property-type.' That tells you *what* you can filter by. But listing a dimension name isn't enough; you need the actual codes. For any specific dimension, run `get_dimension_options`. This pulls all the valid codes and ranges for that variable, guaranteeing your query uses correct inputs.

**Executing the Query:** You've got the Dataset ID, and you’ve validated every filter code with `get_dimensions` and **`get_dimension_options`**. Now it's time to get the numbers. Execute `get_observations`. This tool runs the final query against ONS using your dataset ID and all the necessary filters you defined. It returns structured data points, ready for analysis.

***

This process keeps everything contained: **`search_datasets`** finds IDs based on keywords; **`list_datasets`** lets you browse the entire available catalog; **`get_dataset_info`** gives you methodology and dimensional details for an ID; **`get_dimensions`** maps out all potential filter variables; **`get_dimension_options`** validates specific codes for any variable; and finally, **`get_observations`** executes the query to return structured data points. It's a complete workflow from zero knowledge to final numbers.

## Tools

### search_datasets
Finds relevant dataset IDs, titles, and descriptions by running a keyword search across the entire ONS catalog.

### list_datasets
Browses the complete catalog of 337+ ONS datasets using paginated access.

### get_dataset_info
Retrieves the detailed metadata for a dataset ID, including its dimensions and editions.

### get_dimensions
Lists every available filter variable and its options that can be used to narrow down data results.

### get_dimension_options
Pulls all valid filter values (codes) for a specific dimension within an ONS dataset.

### get_observations
Executes the final query, returning structured observations based on a dataset ID and specified filters.

## Prompt Examples

**Prompt:** 
```
What ONS datasets are available about housing?
```

**Response:** 
```
🔍 **ONS Datasets: housing**

1. house-prices-local-authority — House prices by local authority
2. housing-stock — Dwelling stock estimates
3. new-build — New house building statistics
4. private-rent — Private rental market statistics

4 datasets found matching 'housing'.
```

**Prompt:** 
```
Can you list the variables (dimensions) available for the house-prices dataset?
```

**Response:** 
```
The 'house-prices-local-authority' dataset has 3 dimensions you can filter by:
1. 'geography' (e.g., specific councils/authorities)
2. 'property-type' (e.g., detached, flat, semi-detached)
3. 'time' (year and month).
```

**Prompt:** 
```
What is the latest data on the UK employment rate?
```

**Response:** 
```
I found the 'employment-rate' dataset. Filtering for the latest quarter, the estimated UK employment rate for people aged 16 to 64 was 74.8%, which is a slight increase from the previous quarter.
```

## Capabilities

### Discover Datasets
Search 337+ datasets by keywords (e.g., 'economy', 'population') to find relevant dataset IDs.

### Get Dataset Metadata
Retrieve the full details, methodology, and available versions for a specific ONS dataset ID using `get_dataset_info`.

### Identify Filter Variables
Determine all possible dimension variables (like 'geography' or 'property-type') that can be used to filter the data.

### Validate Dimension Values
Pull a list of valid options for any given filter variable, ensuring your query uses correct codes and ranges.

### Query Observations
Execute the final data request using the dataset ID and all necessary dimension filters to retrieve structured data points.

## Use Cases

### Checking Housing Market Trends
A user asks: 'What was the average house price in London vs. Manchester for detached homes over the last 5 years?' The agent runs `search_datasets` for housing, uses `get_dimensions` to find 'property-type' and 'geography', validates those with options calls, then executes a time series query using `get_observations`.

### Comparing Employment Data
A user needs the latest employment rate data. The agent uses `search_datasets` for 'employment'. It runs `get_dataset_info` to confirm the correct dataset ID and then uses `get_observations` with a time filter to pull the most current quarterly figures.

### Auditing Data Variables
A data team needs to know if 'age' or 'gender' are available variables for a specific dataset. They call `get_dimensions` using the ID, and the server returns all filter options immediately, saving hours of documentation review.

### Broad Topic Exploration
A researcher needs to know what data exists on 'trade' in general. They use `search_datasets`, which instantly returns several IDs (e.g., trade-goods, import-export) allowing them to pick the right starting point without browsing a massive list.

## Benefits

- Stop guessing codes. Use `get_dimension_options` to pull a list of valid filter values for any variable, eliminating guesswork when querying data.
- Get full context on the dataset itself using `get_dataset_info`. You can check methodology and versions before you even run your query.
- Skip manual browsing. Call `search_datasets` first. It immediately returns matching IDs and titles, letting your agent jump straight to the right source data.
- Reduce steps significantly by chaining tools. Your agent flows: `search_datasets` -> `get_dimensions` -> `get_observations`. All in one prompt.
- Handle massive catalogs without limits. The system manages 337+ datasets, covering everything from health and trade to local authority housing statistics.

## How It Works

The bottom line is: you move from a broad topic (search) to validating parameters (dimensions/options), and finally executing a precise data pull (observations).

1. Start by calling `search_datasets` with a keyword (e.g., 'housing') to get potential Dataset IDs.
2. Next, call `get_dimensions` or `get_dataset_info` using the ID to discover all available filter variables and their structure.
3. `get_dimension_options` validates the specific values for those filters. Finally, pass everything into `get_observations` to execute the query.

## Frequently Asked Questions

**How do I find a specific dataset using search_datasets?**
You give `search_datasets` the keywords (e.g., 'pension'). It returns matching IDs, titles, and descriptions from the 337+ catalog instantly.

**What is the difference between get_dimensions and get_dimension_options?**
`get_dimensions` tells you *what* variables exist (like 'property-type'). `get_dimension_options` tells you the specific, valid values for that variable (e.g., 'detached', 'flat', 'semi-detached').

**Can I query data without knowing the dataset ID? Use search_datasets.**
No. While `search_datasets` helps you find the ID, you must still use that specific ID when calling `get_observations` to run a valid query.

**What do I use if I want to see all available datasets? Use list_datasets.**
`list_datasets` provides paginated access to the entire catalog. This is best used when you need an overview or suspect the dataset might be in a category you haven't guessed yet.

**How does the get_dataset_info tool provide details about an ONS dataset's structure?**
It returns deep metadata for a dataset, showing its available dimensions, editions, and versions. You use this to understand the full scope of the data before you even try to query it.

**When using get_observations, what is the best practice for querying time series data?**
You must specify the dimension filters along with the dataset ID. For a complete historical view, set the time filter parameter to *=*. This tells the system to pull the full available time range.

**Before running a query, how should I use get_dimensions to understand necessary filter parameters?**
It lists every available dimension and shows what kind of filters you can apply. Check this tool first; it tells you *what* variables exist for filtering observations.

**If I know the dimension but not its allowed values, what does get_dimension_options do?**
It retrieves every valid option value—like all geography codes or time periods—for a specific dimension. This prevents you from sending an invalid filter that would fail during observation querying.

**How many datasets does the ONS have?**
The ONS API currently exposes 337+ datasets covering economy, population, health, trade, business, census, well-being, and more. New datasets are added regularly as part of the ONS Beta programme.

**What format does the data come in?**
The API provides programmatic access to statistical observations in JSON format. It uses a hypermedia-driven architecture, nesting dimension links, options, and hierarchy information within the responses.

**Is the API free to use?**
Yes, the ONS Developer API is completely free and open, requiring no authentication or API keys, allowing developers unrestricted access to UK national statistics.