---
title: "Get an edition of a dataset"
method: GET
path: "/datasets/{id}/editions/{edition}"
tags: ["Public"]
---

# Get an edition of a dataset

`GET /datasets/{id}/editions/{edition}`

## Request

- Base URL: `https://api.beta.ons.gov.uk/v1`
- URL: `https://api.beta.ons.gov.uk/v1/datasets/{id}/editions/{edition}`
- Auth: one of:
  - none
  - API key in header `Authorization`

Get the latest version of a dataset edition.

## Path parameters

- `edition` string, required
- `id` string, required

## Response `200`

A json object containing the latest version of the edition

- Version: An object containing information about published datasets from the ONS
  - `alerts` Alert[]: A list of alerts, for example corrections after the resource has been published
    - `date` string, date-time, required: The date and time of publication of the version
    - `description` string, required: Detail of what a user needs to be aware of for this dataset
    - `type` 'alert' | 'correction', required: The type of alert. Available types: * `alert`: Important contextual information relevant to the interpretation of a specific version of the dataset. * `correction`: A correction notice summarising the data changes made in the corrected as compared to the superseded version.
  - `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."
  - `dataset_id` string: The unique identifier for a dataset. The dataset ID cannot be changed once the series is first published.
  - `dimensions` Dimension[]: A list of codelists for each dimension of this version
    - `description` string
    - `dimension` string: The name of the dimension
    - `href` string: A link to the code-list entry for the dimension
    - `id` string: The id of the dimension
    - `is_area_type` boolean: Indicates if a dimension is an area-type (census datasets only)
    - `label` string
    - `links` object
      - `code_list` object: The code list related to this dimension
        - `href` string: A URL to the code list
        - `id` string: The unique id for the code list
      - `options` OptionsLink: A list of links related to this dimension
        - `href` string: A URL to a list of options for this dimension
      - `version` VersionLink: The dataset version this resource belongs to
        - `href` string: A URL to the version this resource relates to
        - `id` string: The version number this resource relates to
    - `number_of_options` integer: The number of options available for this dimension
    - `variable` string: The variable name (census datasets only)
  - `distributions` Distribution[], required: A list of representations of the dataset available and how to access them.
    - `title` string, required: The title or label of the distribution.
    - `download_url` string, url, required: URL to directly download a file for the distribution in the specified format.
    - `byte_size` integer: The size in bytes of the download file referenced by `download_url`.
    - `format` 'csv' | 'sdmx' | 'xls' | 'xlsx' | 'csdb' | 'csvw-metadata' | 'zip' | 'json' | 'xml', required: The format for the download file referenced by `download_url`. Formats supported: * `csv` * `sdmx` * `xls` * `xlsx` * `csdb` * `csvw-metadata` * `zip` (for migrated datasets) * `json` * `xml`
    - `media_type` 'text/csv' | 'application/vnd.sdmx.structurespecificdata+xml' | 'application/vnd.ms-excel' | 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' | 'text/plain' | 'application/ld+json' | 'application/zip' | 'application/json' | 'application/xml': The IANA media type for the download file referenced by `download_url`. Media Types supported: * `text/csv`: CSV files * `application/vnd.sdmx.structurespecificdata+xml`: SDMX files * `application/vnd.ms-excel`: Excel (XLS) files * `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`: Excel (XLSX) files * `text/plain`: Plain text (used for CSDB output structured text files) * `application/ld+json`: CSVW metadata files * `application/zip`: ZIP files * `application/json`: JSON files * `application/xml`: XML files
  - `downloads` object: **Deprecated:** These fields have been deprecated and replaced by the `distributions` list. A selection of download objects containing information of downloadable files.
    - `csv` DownloadObject: Object containing information of a downloadable file
      - `href` string: The URL to the generated file
      - `size` string: The size of the file in bytes
    - `csvw` object: Object containing information of a downloadable file
      - `href` string: The URL to the generated file
      - `size` string: The size of the file in bytes
    - `txt` object: Object containing information of a downloadable file
      - `href` string: The URL to the generated file
      - `size` string: The size of the file in bytes
    - `xls` DownloadObject: Object containing information of a downloadable file
      - `href` string: The URL to the generated file
      - `size` string: The size of the file in bytes
  - `edition` string: The unique identifier for an edition of a dataset. The edition ID cannot be changed once first published. If a subsequent version of the edition attempts to change the edition ID, they will be treated as the first version of a new edition instead.
  - `edition_title` string, required: The human readable title of the edition.
  - `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 version was created as part of a dataset migration
  - `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.
  - `latest_changes` LatestChange[]: A list of changes between version of an edition for a dataset and the previous version of the same dataset edition
    - `description` string: A description of what has changed between versions
    - `name` string: The title of the change that has occurred between versions
  - `links` VersionLinks: A list of links related to this resource
    - `dataset` DatasetLink: An object containing the dataset id and link
      - `href` string: A URL to the parent dataset for this resource
      - `id` string: The unique identifier for a dataset. The dataset ID cannot be changed once the series is first published.
    - `dimensions` object
      - `href` string: A URL to list dimensions for this version
    - `edition` EditionLink: An object containing the edition and link
      - `href` string: A URL to the dataset edition for a version
      - `id` string: The unique id for the dataset edition for a version
    - `self` object: A link to this resource
      - `href` string: A URL to this resource
    - `web_page` object: A link to the location of this version of the dataset on the web
      - `href` string: The uri to the location of this version of the dataset on the web
    - `versions` object
      - `href` string: A URL to all versions for an edition of a dataset
  - `lowest_geography` 'oa' | 'lsoa' | 'msoa' | 'wpc' | 'ltla' | 'rgn': The lowest geography this dataset is available at (Census datasets only) Possible geographies: * `oa`: Output Areas * `lsoa`: Lower layer Super Output Areas * `msoa`: Middle layer Super Output Areas * `wpc`: Westminster Parliamentary constituencies * `ltla`: Lower Tier Local Authorities * `rgn`: Regions
  - `quality_designation` 'accredited-official' | 'official' | 'official-in-development' | 'no-accreditation': The official statistics quality designation level of this dataset version. Possible quality designations: * `accredited-official` * `official` * `official-in-development` * `no-accreditation`
  - `related_content` RelatedLink[]: A list of website content related to this version.
    - `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_date` string, date-time, required: The release date of this version of the 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
  - `type` 'filterable' | 'cantabular_flexible_table' | 'cantabular_multivariate_table' | 'static': 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.
  - `usage_notes` UsageNote[]: A list of usage notes relating to the dataset
    - `title` string, required: The title of the usage note.
    - `note` string, required: The usage note text.
  - `version` integer: A number identifying the version for an edition from a dataset

## Other responses

- `400`: Invalid request, dataset id was incorrect
- `404`: No edition of a dataset was found using the id and edition provided
- `500`: Failed to process the request due to an internal error

## Changes

- **2025-02-18** `f5f36bf68ba9`: 1 info
  - the endpoint scheme security `Authorization` was added to the API

[Operation history](https://skmtc.dev/office-of-national-statistics/apis/explore-our-data/changes/datasets/:id/editions/:edition/get.md)

---

[API](https://skmtc.dev/office-of-national-statistics/apis/explore-our-data.md) - [All operations](https://skmtc.dev/office-of-national-statistics/apis/explore-our-data/llms.txt) - [OpenAPI document](https://skmtc.dev/office-of-national-statistics/apis/explore-our-data/revisions/c24bb51d5217?raw)