Sign in

v53

latestSwagger 2.0Open Government Licence v3.0raw.githubusercontent.com2026-08-053554106.9 KB
Private

Create a version

Create a version for a dataset series. This will set the state of the version and dataset series to be associated.

post/datasets/{id}/editions/{edition}/versions

Path parameters

idstring required

ID that represents a dataset

editionstring required

An edition of a dataset

Request body

collection_idstring

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_idstring

The unique identifier for a dataset.

The dataset ID cannot be changed once the series is first published.

editionstring

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_titlestring required

The human readable title of the edition.

is_migrationboolean

Indicates whether this version was created as part of a dataset migration

last_updatedstring 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.

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
release_datestring 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.
versioninteger

A number identifying the version for an edition from a dataset

Example request

{
  "alerts": [
    {
      "description": "This is a description of the changes made as part of the correction or other important notice about this version.",
      "type": "correction"
    }
  ],
  "collection_id": "666c06bc09d337ab9d164c82f8f383c081a4e38cbd91b79d4a23ea0025fecb3f",
  "dataset_id": "my-dataset",
  "dimensions": [
    {
      "links": {
        "version": {
          "href": "https://api.beta.ons.gov.uk/v1/datasets/my-dataset/editions/july-september-2017/versions/5",
          "id": "5"
        }
      }
    }
  ],
  "distributions": [
    {
      "title": "Full Dataset (CSV)",
      "download_url": "https://download.ons.gov.uk/my-dataset-download.csv",
      "byte_size": 4300000
    }
  ],
  "downloads": {
    "csv": {
      "href": "https://download.ons.gov.uk/my-dataset-download.csv",
      "size": "123456"
    },
    "csvw": {
      "href": "https://download.ons.gov.uk/my-dataset.metadata.json",
      "size": "123456"
    },
    "txt": {
      "href": "https://download.ons.gov.uk/my-dataset.metadata.txt",
      "size": "123456"
    },
    "xls": {
      "href": "https://download.ons.gov.uk/my-dataset.xls",
      "size": "123456"
    }
  },
  "edition": "july-september-2017",
  "edition_title": "July to September 2017",
  "is_based_on": {
    "id": "Usual-Residents",
    "type": "cantabular_table"
  },
  "latest_changes": [
    {
      "description": "Some estimates for the periods between April 2011 and March 2019 have been updated. This is because of changes in guidance on suppressing data, where estimates are no longer required to be suppressed solely based on their co-efficient of variation (CV) values.",
      "name": "Data Suppression Changes"
    }
  ],
  "links": {
    "dataset": {
      "href": "https://api.beta.ons.gov.uk/v1/datasets/my-dataset",
      "id": "my-dataset"
    },
    "dimensions": {
      "href": "https://api.beta.ons.gov.uk/v1/datasets/my-dataset/editions/july-september-2017/versions/5/dimensions"
    },
    "edition": {
      "href": "https://api.beta.ons.gov.uk/v1/datasets/my-datasets/editions/july-september-2017",
      "id": "july-september-2017"
    },
    "self": {
      "href": "https://api.beta.ons.gov.uk/v1/datasets/my-dataset/editions/july-september-2017/versions/5"
    },
    "web_page": {
      "href": "https://www.ons.gov.uk/businessindustryandtrade/datasets/my-dataset/editions/july-september-2017/versions/5"
    },
    "versions": {
      "href": "https://api.beta.ons.gov.uk/v1/datasets/my-dataset/editions/july-september-2017/versions"
    }
  },
  "related_content": [
    {
      "href": "https://www.ons.gov.uk/my-related-page",
      "title": "Related Link Title",
      "description": "This is a description of the linked resource."
    }
  ],
  "state": "published",
  "type": "static",
  "usage_notes": [
    {
      "title": "Data Suppression",
      "note": "Individual estimates suppressed with \"[c]\" relate to statistics based on a small number of respondents (< 5). Such values have been suppressed on quality grounds and to maintain confidentiality."
    }
  ],
  "version": 1
}

Response

A json object containing a version