Sign in

v53

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

Create a dataset (deprecated)

Deprecated: This endpoint is being replaced by POST /datasets. Please use POST /datasets and provide the dataset ID in the request body. This endpoint may be removed in a future release.

post/datasets/{id}

Path parameters

idstring required

ID that represents a dataset

Request body

idstring required

The unique identifier for a dataset.

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

canonical_topicstring

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_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."

descriptionstring required

A description for a dataset

is_migrationboolean

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

keywordsstring[]

A list of keywords for a dataset

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.

licensestring required

The license the dataset is released under.

national_statisticboolean

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_releasestring

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.

release_frequencystring

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
subtopicsstring[]

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.

surveystring

The name of the survey the dataset was created from.

titlestring required

The title of the dataset

topicsstring[] 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_measurestring

The unit of measure for the dataset observations

Example request

{
  "id": "my-dataset",
  "canonical_topic": "7779",
  "collection_id": "666c06bc09d337ab9d164c82f8f383c081a4e38cbd91b79d4a23ea0025fecb3f",
  "contacts": [
    {
      "email": "example@ons.gov.uk",
      "name": "Expert Statistical Team",
      "telephone": "+44 1234 111111"
    }
  ],
  "description": "This dataset contains some very interesting data about the UK.",
  "is_based_on": {
    "id": "Usual-Residents",
    "type": "cantabular_table"
  },
  "keywords": [
    "Inflation"
  ],
  "links": {
    "editions": {
      "href": "https://api.beta.ons.gov.uk/v1/datasets/my-dataset/editions"
    },
    "latest_version": {
      "href": "https://api.beta.ons.gov.uk/v1/datasets/my-dataset/editions/july-september-2017/versions/5",
      "id": "5"
    },
    "latest_edition": {
      "href": "https://api.beta.ons.gov.uk/v1/datasets/my-dataset/editions/july-september-2017"
    },
    "self": {
      "href": "https://api.beta.ons.gov.uk/v1/datasets/my-dataset"
    },
    "taxonomy": {
      "href": "https://www.ons.gov.uk/theme/topic"
    }
  },
  "methodologies": [
    {
      "href": "https://www.ons.gov.uk/my-related-page",
      "title": "Related Link Title",
      "description": "This is a description of the linked resource."
    }
  ],
  "next_release": "To be announced",
  "publications": [
    {
      "href": "https://www.ons.gov.uk/my-related-page",
      "title": "Related Link Title",
      "description": "This is a description of the linked resource."
    }
  ],
  "qmi": {
    "href": "https://www.ons.gov.uk/businessindustryandtrade/retailindustry/methodologies/retailsalesindexrsiqmi"
  },
  "related_datasets": [
    {
      "href": "https://www.ons.gov.uk/my-related-page",
      "title": "Related Link Title",
      "description": "This is a description of the linked resource."
    }
  ],
  "related_content": [
    {
      "href": "https://www.ons.gov.uk/my-related-page",
      "title": "Related Link Title",
      "description": "This is a description of the linked resource."
    }
  ],
  "release_frequency": "Monthly",
  "state": "published",
  "subtopics": [
    "7755"
  ],
  "survey": "census",
  "title": "Consumer Prices Index",
  "topics": [
    "7779",
    "7755"
  ],
  "type": "static",
  "unit_of_measure": "Number of people"
}

Response

A json object containing a dataset which has been created

idstring

An unique database id for a dataset

Example response

{
  "id": "DE3BC0B6-D6C4-4E20-917E-95D7EA8C91DC",
  "current": {
    "collection_id": "666c06bc09d337ab9d164c82f8f383c081a4e38cbd91b79d4a23ea0025fecb3f",
    "type": "static",
    "id": "my-dataset",
    "canonical_topic": "7779",
    "contacts": [
      {
        "email": "example@ons.gov.uk",
        "name": "Expert Statistical Team",
        "telephone": "+44 1234 111111"
      }
    ],
    "description": "This dataset contains some very interesting data about the UK.",
    "is_based_on": {
      "id": "Usual-Residents",
      "type": "cantabular_table"
    },
    "keywords": [
      "Inflation"
    ],
    "links": {
      "editions": {
        "href": "https://api.beta.ons.gov.uk/v1/datasets/my-dataset/editions"
      },
      "latest_version": {
        "href": "https://api.beta.ons.gov.uk/v1/datasets/my-dataset/editions/july-september-2017/versions/5",
        "id": "5"
      },
      "latest_edition": {
        "href": "https://api.beta.ons.gov.uk/v1/datasets/my-dataset/editions/july-september-2017"
      },
      "self": {
        "href": "https://api.beta.ons.gov.uk/v1/datasets/my-dataset"
      },
      "taxonomy": {
        "href": "https://www.ons.gov.uk/theme/topic"
      }
    },
    "methodologies": [
      {
        "href": "https://www.ons.gov.uk/my-related-page",
        "title": "Related Link Title",
        "description": "This is a description of the linked resource."
      }
    ],
    "next_release": "To be announced",
    "publications": [
      {
        "href": "https://www.ons.gov.uk/my-related-page",
        "title": "Related Link Title",
        "description": "This is a description of the linked resource."
      }
    ],
    "qmi": {
      "href": "https://www.ons.gov.uk/businessindustryandtrade/retailindustry/methodologies/retailsalesindexrsiqmi"
    },
    "related_datasets": [
      {
        "href": "https://www.ons.gov.uk/my-related-page",
        "title": "Related Link Title",
        "description": "This is a description of the linked resource."
      }
    ],
    "related_content": [
      {
        "href": "https://www.ons.gov.uk/my-related-page",
        "title": "Related Link Title",
        "description": "This is a description of the linked resource."
      }
    ],
    "release_frequency": "Monthly",
    "state": "published",
    "subtopics": [
      "7755"
    ],
    "survey": "census",
    "title": "Consumer Prices Index",
    "topics": [
      "7779",
      "7755"
    ],
    "unit_of_measure": "Number of people"
  },
  "next": {
    "collection_id": "666c06bc09d337ab9d164c82f8f383c081a4e38cbd91b79d4a23ea0025fecb3f",
    "type": "static",
    "id": "my-dataset",
    "canonical_topic": "7779",
    "contacts": [
      {
        "email": "example@ons.gov.uk",
        "name": "Expert Statistical Team",
        "telephone": "+44 1234 111111"
      }
    ],
    "description": "This dataset contains some very interesting data about the UK.",
    "is_based_on": {
      "id": "Usual-Residents",
      "type": "cantabular_table"
    },
    "keywords": [
      "Inflation"
    ],
    "links": {
      "editions": {
        "href": "https://api.beta.ons.gov.uk/v1/datasets/my-dataset/editions"
      },
      "latest_version": {
        "href": "https://api.beta.ons.gov.uk/v1/datasets/my-dataset/editions/july-september-2017/versions/5",
        "id": "5"
      },
      "latest_edition": {
        "href": "https://api.beta.ons.gov.uk/v1/datasets/my-dataset/editions/july-september-2017"
      },
      "self": {
        "href": "https://api.beta.ons.gov.uk/v1/datasets/my-dataset"
      },
      "taxonomy": {
        "href": "https://www.ons.gov.uk/theme/topic"
      }
    },
    "methodologies": [
      {
        "href": "https://www.ons.gov.uk/my-related-page",
        "title": "Related Link Title",
        "description": "This is a description of the linked resource."
      }
    ],
    "next_release": "To be announced",
    "publications": [
      {
        "href": "https://www.ons.gov.uk/my-related-page",
        "title": "Related Link Title",
        "description": "This is a description of the linked resource."
      }
    ],
    "qmi": {
      "href": "https://www.ons.gov.uk/businessindustryandtrade/retailindustry/methodologies/retailsalesindexrsiqmi"
    },
    "related_datasets": [
      {
        "href": "https://www.ons.gov.uk/my-related-page",
        "title": "Related Link Title",
        "description": "This is a description of the linked resource."
      }
    ],
    "related_content": [
      {
        "href": "https://www.ons.gov.uk/my-related-page",
        "title": "Related Link Title",
        "description": "This is a description of the linked resource."
      }
    ],
    "release_frequency": "Monthly",
    "state": "published",
    "subtopics": [
      "7755"
    ],
    "survey": "census",
    "title": "Consumer Prices Index",
    "topics": [
      "7779",
      "7755"
    ],
    "unit_of_measure": "Number of people"
  }
}