Access our data

Welcome to the UKHSA data dashboard API developer's guide. Here, you'll find concise instructions for interacting with our API and comprehensive Swagger documentation detailing endpoint information, parameters, and example responses.

Last updated on Thursday, 21 March 2024 at 02:45pm

Examples

Get data for recorded COVID-19 PCR tests across England

Returns the data associated with the selected metric of COVID-19_testing_PCRcountByDay, which has a theme of infectious_disease, a subtheme of respiratory, a topic of COVID-19, a geography type of Nation and a geography type of England

GET https://api.ukhsa-dashboard.data.gov.uk/themes/infectious_disease/sub_themes/respiratory/topics/COVID-19/geography_types/Nation/geographies/England/metrics/COVID-19_testing_PCRcountByDay

This is a hierarchical API. Due to the nature of the data, there is no guarantee that a particular combination of theme, sub_theme and metric for a given geography will be available. This is dependant on whether that data has been provided to the UKHSA. If the data is not available, the API will return a 200 HTTP OK response with an empty array.

Otherwise, the API will return a 200 HTTP OK response with valid JSON:

{
    "count": 1478,
    "next": "https://api.ukhsa-dashboard.data.gov.uk/themes/infectious_disease/sub_themes/respiratory/topics/COVID-19/geography_types/Nation/geographies/England/metrics/COVID-19_testing_PCRcountByDay?page=2",
    "previous": null,
    "results": [
        {
            "theme": "infectious_disease",
            "sub_theme": "respiratory",
            "topic": "COVID-19",
            "geography_type": "Nation",
            "geography": "England",
            "geography_code": "E92000001",
            "metric": "COVID-19_testing_PCRcountByDay",
            "metric_group": "testing",
            "stratum": "default",
            "sex": "all",
            "age": "all",
            "year": 2020,
            "month": 2,
            "epiweek": 6,
            "date": "2020-02-08",
            "metric_value": 535.0
        },
    ]
}

The API response contains an array of objects in the results field that represent an individual data point.

The theme, sub_theme, topic, metric, geography and geography_code is returned as per the selections via the path parameters.

Each data point includes the following additional fields:

the unique code associated with the selected geography (geography_code)
the group for which this metric belongs to. This can only be one of vaccinations, healthcare, deaths, cases or testing (metric_group)
the smallest subgroup a metric can be broken down into for example by (stratum)
the patient gender. Can only be all, f or m (sex)
the associated age band of the recorded data. For example 15_44 for the age group of 15-44 years old (age)
the year in which the data point was recorded. For example 2024 (year)
the month in which the data point was recorded. The month is represented as a number for example 01 for January (month)epiweek
the date in which the data point relates to. In the format YYYY-MM-DD (date)
the recorded value associated with the data point (metric_value)

The API response also contains the following fields:

the total number of data points which match the provided parameters (count)
a link to the next page of results. If the current page is the last page of results, the value of this field will be null (next)
a link to the previous page of results. If the current page is the first page of results, the value of this field will be null (previous)

API format

By default, the API is intended to function as a browsable hyperlinked API.

You can ensure the data you receive from the API is returned as JSON by using the following query parameter: ?format=json

Filtering your data

This data is paginated by default by a page size of 5. You can either retrieve each page of data by the next page: ?page=2

Or you can request a larger page size in the response from the API via the page_size parameter. ?page_size=50

The maximum supported page size is 365. ?page_size=365

Date

You can filter data which was recorded on a specific date. This is achieved by using the date query parameter as follows: ?date=2024-02-10

Age

You can use the API to filter results pertaining to a specific age group.

For example, to retrieve data associated with the age band of 50 years old to 54 years old: ?age=50-54

Sex

There are 3 options available for the sex query parameter, all, f or m.

f denotes female and m denotes male.

For example, to filter by the female gender group: ?sex=f

Year

To retrieve the data associated with the year of 2024, use: ?year=2024

Stratum

To retrive data associated with a particular stratum, use: ?stratum=default

Epiweek

To retrieve for a particular epidemiological week, use: ?epiweek=1