---
title: "List datasets"
method: GET
path: "/datasets"
tags: ["Public"]
---

# List datasets

`GET /datasets`

Returns a list of all datasets available via the ONS APIs.

## Query parameters

- `is_based_on` string
- `type` string
- `limit` integer
- `offset` integer
- `sort_order` string
- `id` string

## Response `200`

A json list containing datasets which have been published

- Datasets — A list of datasets
  - `count` integer — The number of items returned.
  - `limit` integer — The number of items requested.
  - `offset` integer — The offset of the first item to retrieve, starting at 0. Use this parameter as a pagination mechanism along with the limit parameter
  - `total_count` integer — The total number of items available.
  - `items` Dataset[]
    - `id` string, required — The unique identifier for a dataset. The dataset ID cannot be changed once the series is first published.
    - `canonical_topic` string — **Deprecated:** This field has been deprecated and replaced by the `topics` field. The canonical topic id for this dataset. This indicates which topic this dataset belongs to within the topic taxonomy.
    - `collection_id` string — **Internal Only: This is an internal only field and is not present once a dataset is published.** The id of the unpublished collection (of datasets) that this dataset is associated with."
    - `contacts` Contact[], required — A list containing contact details of statisticians for a dataset
      - `email` string, email, required — Email address to contact the statistician or statistician group responsible for the dataset.
      - `name` string, required — The name of the statistician or statistician group contact point responsible for the dataset.
      - `telephone` string — Telephone number to contact the statistician or statistician group responsible for the dataset.
    - `description` string, required — A description for a dataset
    - `is_based_on` IsBasedOn — Information about the population-type that the dataset is based on (census 2021 only)
      - `id` string — The population-type that the dataset is based on
      - `type` string — The type of the dataset
    - `is_migration` boolean — Indicates whether this dataset series was created as part of a dataset migration
    - `keywords` string[] — A list of keywords for a dataset
    - `last_updated` string, date-time — The date and time of the last update to the resource. For published resources this is the date and time the latest change was published.
    - `license` string, required — The license the dataset is released under.
    - `links` DatasetLinks — Navigational links related to the dataset resource to aid in API navigation.
      - `editions` object
        - `href` string — A URL to all editions for this dataset
      - `latest_version` LatestVersionLink — An object containing the latest version id and link
        - `href` string — A link to the latest version and edition of the dataset
        - `id` string — The unique id for the latest version of a dataset
      - `latest_edition` object — An object containing a link to the latest edition of the dataset.
        - `href` string — A link to the latest edition of the dataset.
      - `self` object — A link to this resource
        - `href` string — A URL to this resource
      - `taxonomy` object — The taxonomy path of the dataset's canonical topic.
        - `href` string — **Deprecated:** This field has been deprecated and will be removed in future. It is strongly advised that you do not use this field as topics will move in the hierarchy and therefore the value returned here will become outdated. Use the first entry in the `topics` list in combination with the Topics API instead. The taxonomy path of the canonical topic for the dataset at the time of publish.
    - `methodologies` RelatedLink[] — A list of methodologies for the dataset.
      - `href` string, url, required — The url of the linked item.
      - `title` string, required — The title of the linked item.
      - `description` string — The description of the linked item.
    - `national_statistic` boolean — **Deprecated:** This field has been deprecated and replaced with the `quality_designation` field under at the edition level in order to correctly represent the three potential quality designations under the updated Code of Practice for Statistics. The flag indicating the latest version of the dataset has `accredited` designation as granted under the Code of Practice for Statistics.
    - `next_release` string — The next release date for a dataset. This field is a free text field rather than a date-time format and may be a date range, to be confirmed or some other description.
    - `publications` RelatedLink[] — A list of publications related to this dataset.
      - `href` string, url, required — The url of the linked item.
      - `title` string, required — The title of the linked item.
      - `description` string — The description of the linked item.
    - `publishers` Publisher[] — A list of the publishers for the dataset.
      - `name` string, required — The name of the publisher
      - `href` string, url, required — A link to the publishers homepage
    - `qmi` QMILink
      - `href` string, url, required — The url to the quality and methodology information sheet for the dataset.
    - `related_datasets` RelatedLink[] — A list of other datasets related to this dataset.
      - `href` string, url, required — The url of the linked item.
      - `title` string, required — The title of the linked item.
      - `description` string — The description of the linked item.
    - `related_content` RelatedLink[] — A list of website content related to this dataset.
      - `href` string, url, required — The url of the linked item.
      - `title` string, required — The title of the linked item.
      - `description` string — The description of the linked item.
    - `release_frequency` string — The release frequency of a dataset
    - `state` 'created' | 'completed' | 'failed' | 'edition-confirmed' | 'associated' | 'published' — The state of the resource, can only be one of the following: * created * completed (instances only) * failed (instances only) * edition-confirmed (instances and versions only) * associated (not editions) * published
    - `subtopics` string[] — **Deprecated:** This field is being deprecated and replaced by the `topics` field. A list of subtopic ids that the dataset relates to within the topic taxonomy.
    - `survey` string — The name of the survey the dataset was created from.
    - `title` string, required — The title of the dataset
    - `topics` string[], required — A list of topic IDs that the dataset relates to within the topic taxonomy. This field consolidates the previously separate `canonical_topic` and `subtopics` fields.
    - `type` 'filterable' | 'cantabular_flexible_table' | 'cantabular_multivariate_table' | 'static', required — The type of dataset as determined by the backing data store. Used to determine which functionality is available for a dataset. Available types: * `filterable`: Datasets provided by Customise My Data product providing ability to filter observations by specific dimension options. * `cantabular_flexible_table`: Dataset derived from a `cantabular_blob` allowing the option to change the geography level and filter on specific areas. * `cantabular_multivariate_table`: Dataset with multiple variables derived from a `cantabular_blob` allowing the option to customise the dataset by adding or removing dimensions as well as by changing the geography level and dimension categorisation. * `static`: Datasets available as a flat file download without additional querying capabilities.
    - `unit_of_measure` string — The unit of measure for the dataset observations

## Other responses

- `400` — Parameter is_based_on or type was sent but no value was provided
- `404` — No dataset was found with the population-type provided
- `500` — Failed to process the request due to an internal error

---

[API](https://skmtc.net/office-of-national-statistics/apis/explore-our-data.md) · [All operations](https://skmtc.net/office-of-national-statistics/apis/explore-our-data/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/office-of-national-statistics/explore-our-data/versions/269ed359fb27/schema)