/datasets/{id}/editions/{edition}/versions
GET
Get a list of all versions for an edition of a dataset
Parameters
| Name | Type | Description |
|---|---|---|
| edition | path | An edition of a dataset |
| id | path | Id that represents a dataset |
| limit | query | Maximum number of items that will be returned. A value of zero will return zero items. The default value is 20, and the maximum limit allowed is 1000 |
| offset | query | Starting index of the items array that will be returned. By default it is zero, meaning that the returned items will start from the beginning. |
Responses
200: A json list containing all versions for a set type of dataset and edition
Example value
{
"type": "object",
"properties": {
"count": {
"description": "The number of versions returned for an edition of a dataset",
"type": "integer",
"readOnly": true
},
"items": {
"description": "An array of Datasets",
"type": "array",
"items": {
"description": "An object containing information about published datasets from the ONS",
"type": "object",
"required": [
"release_date"
],
"properties": {
"alerts": {
"description": "A list of alerts, for example corrections after the resource has been published",
"type": "array",
"items": {
"description": "Important information relating to a version of a dataset",
"type": "object",
"properties": {
"date": {
"description": "The date and time of when an alert took place",
"type": "string"
},
"description": {
"description": "Detail of what a user needs to be aware of for this dataset",
"type": "string"
},
"type": {
"description": "The type of alert",
"type": "string",
"example": "correction"
}
}
}
},
"collection_id": {
"description": "The id of the unpublished collection (of datasets) that this dataset is associated with",
"type": "string"
},
"dataset_id": {
"description": "The identifier for the dataset.",
"type": "string"
},
"dimensions": {
"description": "A list of codelists for each dimension of this version",
"type": "array",
"items": {
"description": "A single dimension within a dataset",
"type": "object",
"properties": {
"description": {
"type": "string"
},
"dimension": {
"description": "The name of the dimension",
"type": "string"
},
"href": {
"description": "A link to the code-list entry for the dimension",
"type": "string"
},
"id": {
"description": "The id of the dimension",
"type": "string"
},
"is_area_type": {
"description": "Indicates if a dimension is an area-type (census datasets only)",
"type": "boolean"
},
"label": {
"type": "string"
},
"links": {
"type": "object",
"properties": {
"code_list": {
"description": "The code list related to this dimension",
"type": "object",
"properties": {
"href": {
"description": "A URL to the code list",
"type": "string"
},
"id": {
"description": "The unique id for the code list",
"type": "string"
}
}
},
"options": {
"description": "A list of links related to this dimension",
"type": "object",
"properties": {
"href": {
"description": "A URL to a list of options for this dimension",
"type": "string"
}
}
},
"version": {
"description": "The dataset version this resource belongs to",
"type": "object",
"properties": {
"href": {
"description": "A URL to the version this resource relates to",
"type": "string"
},
"id": {
"description": "The version number this resource relates to",
"type": "string"
}
}
}
}
},
"number_of_options": {
"description": "The number of options available for this dimension",
"type": "integer"
},
"variable": {
"description": "The variable name (census datasets only)",
"type": "string"
}
}
}
},
"downloads": {
"description": "A selection of download objects containing information of downloadable files.",
"type": "object",
"properties": {
"csv": {
"description": "Object containing information of a downloadable file",
"type": "object",
"properties": {
"href": {
"description": "The URL to the generated file",
"type": "string"
},
"size": {
"description": "The size of the file in bytes",
"type": "string"
}
}
},
"csvw": {
"description": "Object containing information of a downloadable file",
"type": "object",
"properties": {
"href": {
"description": "The URL to the generated file",
"type": "string"
},
"size": {
"description": "The size of the file in bytes",
"type": "string"
}
}
},
"txt": {
"description": "Object containing information of a downloadable file",
"type": "object",
"properties": {
"href": {
"description": "The URL to the generated file",
"type": "string"
},
"size": {
"description": "The size of the file in bytes",
"type": "string"
}
}
},
"xls": {
"description": "Object containing information of a downloadable file",
"type": "object",
"properties": {
"href": {
"description": "The URL to the generated file",
"type": "string"
},
"size": {
"description": "The size of the file in bytes",
"type": "string"
}
}
}
}
},
"edition": {
"description": "The dataset edition for this version",
"type": "string",
"readOnly": true
},
"id": {
"description": "The identifier for this version of an edition for a dataset",
"type": "string"
},
"is_based_on": {
"description": "Information about the population-type that the dataset is based on (census 2021 only)",
"type": "object",
"properties": {
"id": {
"description": "The population-type that the dataset is based on",
"type": "string",
"example": "Usual-Residents"
},
"type": {
"description": "The type of the dataset",
"type": "string",
"example": "cantabular_table"
}
}
},
"latest_changes": {
"description": "A list of changes between version of an edition for a dataset and the previous version of the same dataset edition",
"type": "array",
"items": {
"description": "A single change between this version and the previous version of an edition for a dataset",
"type": "object",
"properties": {
"description": {
"description": "A description of what has changed between versions",
"type": "string"
},
"name": {
"description": "The name of the change that has occurred between versions",
"type": "string",
"example": "changes in classification"
},
"type": {
"description": "The type of change",
"type": "string",
"example": "summary of changes"
}
}
}
},
"links": {
"description": "A list of links related to this resource",
"type": "object",
"properties": {
"dataset": {
"description": "An object containing the dataset id and link",
"type": "object",
"properties": {
"href": {
"description": "A URL to the parent dataset for this resource",
"type": "string",
"example": "http://localhost:8080/datasets/DE3BC0B6-D6C4-4E20-917E-95D7EA8C91DC"
},
"id": {
"description": "The unique id for the dataset of this version",
"type": "string"
}
},
"readOnly": true
},
"dimensions": {
"type": "object",
"properties": {
"href": {
"description": "A URL to list dimensions for this version",
"type": "string",
"example": "http://localhost:8080/datasets/DE3BC0B6-D6C4-4E20-917E-95D7EA8C91DC/editions/2017/versions/2/dimensions"
}
},
"readOnly": true
},
"edition": {
"description": "An object containing the edition and link",
"type": "object",
"properties": {
"href": {
"description": "A URL to the dataset edition for a version",
"type": "string",
"example": "http://localhost:8080/datasets/DE3BC0B6-D6C4-4E20-917E-95D7EA8C91DC/editions/2017"
},
"id": {
"description": "The unique id for the dataset edition for a version",
"type": "string"
}
},
"readOnly": true
},
"self": {
"description": "A link to this resource",
"type": "object",
"properties": {
"href": {
"description": "A URL to this resource",
"type": "string"
}
},
"readOnly": true
},
"spatial": {
"type": "object",
"properties": {
"href": {
"description": "A url to a list of geography ranges for the version of the dataset",
"type": "string"
}
}
}
}
},
"lowest_geography": {
"description": "The lowest geography this dataset is available at (Census datasets only)",
"type": "string"
},
"release_date": {
"description": "The release date of this version of the dataset",
"type": "string"
},
"state": {
"description": "The state of the resource, can only be one of the following:\n * created\n * completed (instances only)\n * failed (instances only)\n * edition-confirmed (instances and versions only)\n * associated (not editions)\n * published\n",
"type": "string"
},
"temporal": {
"description": "A list of frequencies the dataset covers for a particular period of time",
"type": "array",
"items": {
"type": "object",
"properties": {
"end_date": {
"description": "The end date of the time period in which the version of the dataset covers this frequency",
"type": "string"
},
"frequency": {
"description": "The time frequency the version of the dataset covers for the period of time between start_date and end_date",
"type": "string"
},
"start_date": {
"description": "The start date of the time period in which the version of the dataset covers this frequency",
"type": "string"
}
}
}
},
"type": {
"description": "The type of dataset - e.g. cantabular_flexible_table",
"type": "string"
},
"usage_notes": {
"description": "A list of usage notes relating to the dataset",
"type": "array",
"items": {
"description": "A note relating to the dataset. This will appear in downloaded datasets",
"type": "object",
"properties": {
"note": {
"description": "The content of the note",
"type": "string"
},
"title": {
"description": "The title of the note",
"type": "string"
}
}
}
},
"version": {
"description": "A number identifying the version for an edition from a dataset",
"type": "integer",
"readOnly": true,
"example": 1
}
}
}
},
"limit": {
"description": "The number of versions requested for an edition of a dataset",
"type": "integer"
},
"offset": {
"description": "The first row of versions for an edition of a dataset to retrieve, starting at 0. Use this parameter as a pagination mechanism along with the limit parameter",
"type": "integer"
},
"total_count": {
"description": "The total number of versions for an edition of a dataset",
"type": "integer",
"readOnly": true
}
}
}400: Invalid request, reasons can be one of the following: * dataset id was incorrect * edition was incorrect
Example value
null404: No versions found using the id and edition provided
Example value
null500: Failed to process the request due to an internal error
Example value
null