# info.description
Docs for the API which supports the UKHSA Data Dashboard.

# paths./.get.description
**Using the API**

Use the API to extract and save data from the UKHSA data dashboard.
To start, please select and filter to the specific data metric you’re interested in.

The hyperlinked API will guide you to the data you’re looking for.
By clicking on each link, you’ll be shown the next options available for the data you’ve selected.
The data selection is structured, meaning the option you select will determine the options available.

---

This is how the data is structured:

- Theme – the overall subgroup of the data. For example, **infectious_disease**

- Sub_theme – the group the data falls in within the theme. For example, **respiratory**

- Topic – the type of data within the sub-theme. For example, **COVID-19**

- Geography_type – the type of geographical area for the data. For example, **NHS region**

- Geography – the specific geographical area related to the type. For example, **London**

- Metric – the name of the metric you’re interested in. For example, **COVID-19_cases_casesByDay**

- Timeseries – further filtering of the data

---

The structure of the URL stays the same for each API query, following the filtering selection process.
For example, the data filtering shown above (in bold) would produce this URL:

```
/themes/infectious_disease/sub_themes/respiratory/topics/COVID-19/geography_types/NHS_region/geographies/London/metrics/COVID-19_cases_casesByDay
```

The overall category is plural (in this example, themes)
which is then followed by the detail selected (in this example, infectious_diseases).

Unlike the coronavirus (COVID-19) dashboard API, you cannot extract all the data across a topic or geography type.
The API is designed for you to be selective by data type, topic, geography and metric.

# paths./api/schema/.get.description
OpenApi3 schema for this API. Format can be selected via content negotiation.

- YAML: application/vnd.oai.openapi
- JSON: application/vnd.oai.openapi+json

# paths./health/.get.description
This health probe can be used to determine whether the service is ready.

# paths./themes/.get.description
This endpoint returns a list of all available **themes** and hyperlinks to their corresponding detail view.

A `theme` is the largest topical subgroup e.g. **infectious_disease**.

# paths./themes/{theme}.get.description
This endpoint returns a hyperlink to the next step in the data hierarchy.

In this case, the next step in the data hierarchy is **sub_themes**.

# paths./themes/{theme}/sub_themes/.get.description
This endpoint returns a list of all available **sub_themes** and hyperlinks to their corresponding detail view.

The `sub_theme` field is positioned 1 step below `theme`.

A `sub_theme` is a topical subgroup  e.g. **respiratory**

# paths./themes/{theme}/sub_themes/{sub_theme}.get.description
This endpoint returns a hyperlink to the next step in the data hierarchy.

In this case, the next step in the data hierarchy is **topics**.

# paths./themes/{theme}/sub_themes/{sub_theme}/topics.get.description
This endpoint returns a list of all available **topics** and hyperlinks to their corresponding detail view.

The `topic` field is positioned 1 step below `sub_theme`.

A `topic` is the name of the topic/threat e.g. **COVID-19**

# paths./themes/{theme}/sub_themes/{sub_theme}/topics/{topic}.get.description
This endpoint returns a hyperlink to the next step in the data hierarchy.

In this case, the next step in the data hierarchy is **geography_type**.

# paths./themes/{theme}/sub_themes/{sub_theme}/topics/{topic}/geography_.get.description
This endpoint returns a list of all available geography types and hyperlinks to their corresponding detail view.

The `geography_type` field is positioned 1 step below `topic`.

A `geography_type` is the type of geography e.g. **Nation**

# paths./themes/{theme}/sub_themes/{sub_theme}/topics/{topic}/geography_.get.description
This endpoint returns a hyperlink to the next step in the data hierarchy.

In this case, the next step in the data hierarchy is **geography**.

# paths./themes/{theme}/sub_themes/{sub_theme}/topics/{topic}/geography_.get.description
This endpoint returns a list of all available geographies and hyperlinks to their corresponding detail view.

The `geography` field is positioned 1 step below `geography_type`.

A `geography` is the value of the geography e.g. **London**

# paths./themes/{theme}/sub_themes/{sub_theme}/topics/{topic}/geography_.get.description
This endpoint returns a hyperlink to the next step in the data hierarchy.

In this case, the next step in the data hierarchy is **metric**.

# paths./themes/{theme}/sub_themes/{sub_theme}/topics/{topic}/geography_.get.description
This endpoint returns a list of all available metrics and hyperlinks to their corresponding detail view.

The `metric` field is positioned 1 step below `geography`.

A `metric` is the name of the metric being queried for e.g. **COVID-19_deaths_ONSByDay**

# paths./themes/{theme}/sub_themes/{sub_theme}/topics/{topic}/geography_.get.description
This endpoint will provide the full timeseries of a slice of data.

There are a set of mandatory URL parameters and optional query parameters:

Note that by default, results are paginated by a page size of 5

This page size can be changed using the *page_size* parameter.
The maximum supported page size is **365**.

---

Whereby the mandatory URL parameters are as follows in order from first to last:

- `theme` - The largest topical subgroup e.g. **infectious_disease**

- `sub_theme` - A topical subgroup e.g. **respiratory**

- `topic` - The name of the topic e.g. **COVID-19**

- `geography_type` - The type of the geography type e.g. **Nation**

- `geography` - The name of the geography associated with metric  e.g. **London**

- `metric` - The name of the metric being queried for e.g. **COVID-19_deaths_ONSByDay**

---

From here you can filter the data further via a set of optional query parameters:

- `stratum` - Smallest subgroup a metric can be broken down into e.g. ethnicity, testing pillar

- `age` - Smallest subgroup a metric can be broken down into e.g. **15_44** for the age group of 15-44 years

- `sex` - Patient gender e.g. **f** for Female or **all** for all genders

- `year` - Epi year of the metrics value (important for annual metrics) e.g. **2020**

- `month` - Epi month of the metric value (important for monthly metrics) e.g. **12**

- `epiweek` - Epi week of the metric value (important for weekly metrics) e.g. **30**

- `date` - The date which this metric value was recorded in the format **YYYY-MM-DD** e.g. **2020-07-20**

# paths./themes/{theme}/sub_themes/{sub_theme}/topics/{topic}/geography_.get.parameters[].description
A page number within the paginated result set.