swagger: "2.0" info: description: | Dataset catalogue used to find information about data published by the ONS. `Datasets` are published in unique `versions`, which are categorized by `edition`. Data in each version is broken down by `dimensions`, and a unique combination of dimension `options` in a version can be used to retrieve `observation` level data. Note: As of the latest update, the `@context` field has been removed from all dataset endpoints to improve response performance and correct data structure." version: "1.0.0" title: "Explore our data" license: name: "Open Government Licence v3.0" url: "https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/" basePath: "/v1" tags: - name: "Public" description: Endpoints available on public API. - name: "Private" description: Internal only endpoints. host: api.beta.ons.gov.uk schemes: - "https" parameters: after_filter: name: after type: string format: date-time description: "The date from which to query dataset events" in: query required: false before_filter: name: before type: string format: date-time description: "The date to which to query dataset events" in: query required: false dataset: name: dataset description: "A unique id for a dataset to filter on" in: query type: string dimension: name: dimension description: "A dimension from a dataset" in: path required: true type: string patch_options: required: true name: patch schema: $ref: "#/definitions/PatchOptions" description: "A list of patch operations for a dimension option" in: body patch_dimensions: required: true name: patch schema: $ref: "#/definitions/PatchDimensions" description: "A list of patch operations for a dimension" in: body edition: name: edition description: "An edition of a dataset" in: path required: true type: string event: name: event description: "An event that occurs when importing a dataset" in: body schema: $ref: "#/definitions/Event" dataset_id: name: id description: "ID that represents a dataset" in: path required: true type: string import_tasks: name: import_tasks description: "A request body to update the state of an import task" in: body schema: $ref: "#/definitions/ImportTasks" inserted_observations: name: inserted_observations description: "A value to increment the inserted_observations within an instance" in: path required: true type: integer instance_id: name: instance_id description: "A unique id for an instance" in: path required: true type: string instance: name: instance description: "An instance related to an import job and dataset" in: body required: true schema: $ref: "#/definitions/Instance" new_dataset: name: dataset description: "A new dataset" in: body required: true schema: $ref: "#/definitions/Dataset" new_version: name: new_version description: "A new version for an edition of a dataset" in: body required: true schema: $ref: "#/definitions/Version" node_id: name: node_id description: "An unique node id" in: path required: true type: string newInstance: name: instance description: "An instance related to an import job" in: body required: true schema: $ref: "#/definitions/NewInstance" option: name: option description: "A option to set within a type" in: path required: true type: string state: name: "state" description: "A comma separated list of state values to filter on (e.g. ‘completed,edition-confirmed’)" in: query type: string single-state: name: "state" description: "A state value to filter on (e.g. ‘published’)" in: query type: string published: name: "published" description: "A boolean value which indicates whether to include published editions/versions in the response" in: query type: boolean update_dataset: name: dataset description: "An update to a dataset" in: body required: true schema: $ref: "#/definitions/Dataset" update_dimension: name: dimension description: "A dimension object to update for a given instance" in: body required: true schema: $ref: "#/definitions/UpdateInstanceDimension" update_dimension_option_request: name: dimension_option description: "A dimension option from an instance" in: body schema: $ref: "#/definitions/UpdateDimensionOptionRequest" version: name: version description: "A version of a dataset" in: path required: true type: string version_update: name: version_update description: | Update to a version for an edition of a dataset. This model allows for the updating the deprecated `downloads` map for backwards compatability. in: body required: true schema: allOf: - $ref: "#/definitions/Version" - properties: downloads: allOf: - readOnly: false is_latest: name: is_latest description: "A boolean value which, when true, sets the latest_version information at series level using the version number and edition provided in the path" in: query required: false type: boolean limit: name: limit description: "Maximum number of items that will be returned. A value of zero will return zero items." in: query required: false type: integer default: 20 minimum: 0 maximum: 1000 offset: name: offset description: "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." in: query required: false type: integer default: 0 minimum: 0 sort_order: name: sort_order description: "Value for the sort order of the array that will be returned. Default value is DESC (z-a) for descending order, for the ascending order ASC can be used." in: query required: false type: string default: DESC dataset_id_query: name: id description: "ID that represents a dataset" in: query required: false type: string edition_query: name: edition description: "An edition of a dataset to search on" in: query required: false type: string ids: name: id description: "List of ids, as comma separated values and/or as multiple query parameters with the same key (e.g. 'id=op1,op2&id=op3'). It defines the IDs that we want to retrieve. If provided, it takes precedence over offset and limit." in: query required: false type: string if_match: name: If-Match required: false description: "Filter resource version, as returned by a previous ETag, to be validated; or '*' to skip the version check" in: header type: string is_based_on: name: is_based_on required: false description: "A population type to search on to return datasets that are associated with that population type e.g. Usual-Residents. This is applicable to Census 2021 datasets only." in: query type: string type: name: type required: false description: "A filter to search the datasets by dataset type e.g. type=static" in: query type: string metadata_update: name: metadata_update in: body required: true schema: $ref: "#/definitions/Metadata" securityDefinitions: Authorization: name: Authorization description: "Access token provided by Auth Service in a Bearer format. Can be a human or service user token." in: header type: apiKey DownloadServiceAPIKey: name: X-Download-Service-Token description: "API key used to allow the download service to access public and private links to a download" in: header type: apiKey paths: /datasets: get: tags: - "Public" summary: "List datasets" description: "Returns a list of all datasets available via the ONS APIs." parameters: - $ref: "#/parameters/is_based_on" - $ref: "#/parameters/type" - $ref: "#/parameters/limit" - $ref: "#/parameters/offset" - $ref: "#/parameters/sort_order" - $ref: "#/parameters/dataset_id_query" security: - {} - Authorization: [] produces: - "application/json" responses: 200: description: "A json list containing datasets which have been published" schema: $ref: "#/definitions/Datasets" headers: ETag: description: The RFC7232 ETag header field the of the resource, where the resource is the response to the specific query paramaters. This is used for setting the `If-None-Match` headers on subsequent requests to check for changes. type: string Cache-Control: description: The RFC9111 Cache-Control header field for the response which instructs how to handle caching the resource. type: string 400: description: "Parameter is_based_on or type was sent but no value was provided" 404: description: "No dataset was found with the population-type provided" 500: $ref: "#/responses/InternalError" post: tags: - "Private" summary: "Create a new dataset" description: "Allows an authenticated and authorised user to create a new dataset. The dataset ID should be included in the request body." parameters: - $ref: "#/parameters/new_dataset" security: - Authorization: [] produces: - "application/json" responses: 201: description: "A JSON object containing the newly created dataset" schema: $ref: "#/definitions/Dataset" 400: description: "Invalid request body" 401: description: "Unauthorised to create/overwrite dataset" 409: description: "dataset already exists" 500: $ref: "#/responses/InternalError" /datasets/{id}: post: tags: - "Private" summary: "Create a dataset (deprecated)" description: | **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. deprecated: true parameters: - $ref: "#/parameters/dataset_id" - $ref: "#/parameters/new_dataset" security: - Authorization: [] produces: - "application/json" responses: 201: description: "A json object containing a dataset which has been created" schema: $ref: "#/definitions/NewDatasetResponse" 400: description: "Invalid request body" 401: description: "Unauthorised to create/overwrite dataset" 403: description: "Forbidden to overwrite dataset, already published" 500: $ref: "#/responses/InternalError" get: tags: - "Public" summary: "Get a dataset" description: "The dataset contains all high level information, for additional details see editions or versions of a dataset. " parameters: - $ref: "#/parameters/dataset_id" security: - {} - Authorization: [] responses: 200: description: "A json object for a single Dataset" schema: $ref: "#/definitions/Dataset" headers: ETag: description: The RFC7232 ETag header field. Defines the unique entity tag for the current state of the resource. This is used for setting the `If-Match` and `If-None-Match` headers on subsequent requests. type: string Cache-Control: description: The RFC9111 Cache-Control header field for the response which instructs how to handle caching the resource. type: string 404: description: "No dataset was found using the id provided" 500: $ref: "#/responses/InternalError" put: tags: - "Private" summary: "Update a dataset" description: "Update the metadata for the next release of the dataset. The dataset contains all high level information, for additional details see editions or versions of a dataset." parameters: - $ref: "#/parameters/dataset_id" - $ref: "#/parameters/update_dataset" security: - Authorization: [] responses: 200: description: "A json object for a single Dataset" 400: description: "Bad Request due to invalid json in the request body" 401: description: "Unauthorised to update dataset" 409: description: "Dataset title already exists" 404: description: "No dataset was found using the id provided" 500: $ref: "#/responses/InternalError" delete: tags: - "Private" summary: "Delete a dataset" description: "Delete an existing dataset" parameters: - $ref: "#/parameters/dataset_id" security: - Authorization: [] responses: 204: description: "The dataset was successfully deleted" 401: description: "Unauthorised to delete the dataset" 403: description: "Forbidden to delete dataset, already published" 500: $ref: "#/responses/InternalError" /dataset-editions: get: tags: - "Private" summary: "Get a list of dataset series that have unpublished versions" description: "Get a list of dataset series that have unpublished versions. This is used to easily determine versions/editions of series that are awaiting publication." parameters: - $ref: "#/parameters/single-state" - $ref: "#/parameters/published" - $ref: "#/parameters/limit" - $ref: "#/parameters/offset" security: - Authorization: [] responses: 200: description: "A json list containing all dataset editions that have unpublished versions" schema: type: array items: $ref: "#/definitions/DatasetEdition" 400: description: "Invalid query parameter" 401: description: "Unauthorised to access endpoint" 404: description: "No versions were found" 500: $ref: "#/responses/InternalError" /dataset-events: get: tags: - "Private" summary: "List all events relating to a dataset, edition, or version for static datasets only." description: "Returns a list of events for a dataset, edition, or version for static datasets only." parameters: - $ref: "#/parameters/dataset_id_query" - $ref: "#/parameters/edition_query" - $ref: "#/parameters/after_filter" - $ref: "#/parameters/before_filter" - $ref: "#/parameters/limit" - $ref: "#/parameters/offset" security: - {} - Authorization: [] produces: - "application/json" responses: 200: description: The list of change audit events for a dataset or edition. headers: ETag: description: The RFC9110 ETag header field. Defines the unique entity tag for the current state of the resource. This is used for setting the `If-Match` and `If-None-Match` headers on subsequent requests. type: string pattern: ^(?:W/)?"(?:[!#-~])+"$ Cache-Control: description: The RFC9111 Cache-Control header field for the response which instructs how to handle caching the resource. type: string schema: $ref: "#/definitions/AuditEventsList" 400: description: "Invalid query parameter" 401: description: "Unauthorised to access endpoint" 404: description: "No dataset or editions were found" 500: $ref: "#/responses/InternalError" /datasets/{id}/editions: get: tags: - "Public" summary: "Get a list of editions of a dataset" description: "Get a list of editions of a dataset. Each edition returns the latest version of that edition." parameters: - $ref: "#/parameters/dataset_id" - $ref: "#/parameters/limit" - $ref: "#/parameters/offset" security: - {} - Authorization: [] responses: 200: description: "A json list containing all editions for a dataset" schema: $ref: "#/definitions/Editions" headers: ETag: description: The RFC7232 ETag header field the of the resource, where the resource is the response to the specific query paramaters. This is used for setting the `If-None-Match` headers on subsequent requests to check for changes. type: string Cache-Control: description: The RFC9111 Cache-Control header field for the response which instructs how to handle caching the resource. type: string 400: description: "Invalid request, dataset id was incorrect" 404: description: "No editions were found for the id provided" 500: $ref: "#/responses/InternalError" /datasets/{id}/editions/{edition}: get: tags: - "Public" summary: "Get an edition of a dataset" description: "Get the latest version of a dataset edition." parameters: - $ref: "#/parameters/edition" - $ref: "#/parameters/dataset_id" security: - {} - Authorization: [] responses: 200: description: "A json object containing the latest version of the edition" schema: $ref: "#/definitions/Version" headers: ETag: description: The RFC7232 ETag header field. Defines the unique entity tag for the current state of the resource. This is used for setting the `If-Match` and `If-None-Match` headers on subsequent requests. type: string Cache-Control: description: The RFC9111 Cache-Control header field for the response which instructs how to handle caching the resource. type: string 400: description: "Invalid request, dataset id was incorrect" 404: description: "No edition of a dataset was found using the id and edition provided" 500: $ref: "#/responses/InternalError" /datasets/{id}/editions/{edition}/versions: get: tags: - "Public" summary: "List the edition's version history" description: "Get a list of all versions for a dataset edition." parameters: - $ref: "#/parameters/edition" - $ref: "#/parameters/dataset_id" - $ref: "#/parameters/limit" - $ref: "#/parameters/offset" security: - {} - Authorization: [] - Authorization: [] DownloadServiceAPIKey: [] responses: 200: description: "A json list containing all versions for a set type of dataset and edition" schema: $ref: "#/definitions/Versions" headers: ETag: description: The RFC7232 ETag header field the of the resource, where the resource is the response to the specific query paramaters. This is used for setting the `If-None-Match` headers on subsequent requests to check for changes. type: string Cache-Control: description: The RFC9111 Cache-Control header field for the response which instructs how to handle caching the resource. type: string 400: description: | Invalid request, reasons can be one of the following: * dataset id was incorrect * edition was incorrect 404: description: "No versions found using the id and edition provided" 500: $ref: "#/responses/InternalError" post: tags: - "Private" summary: "Create a version" description: "Create a version for a dataset series. This will set the state of the version and dataset series to be associated." parameters: - $ref: "#/parameters/dataset_id" - $ref: "#/parameters/edition" - $ref: "#/parameters/new_version" security: - {} - Authorization: [] responses: 201: description: "A json object containing a version" schema: $ref: "#/definitions/Version" 400: description: | Invalid request, reasons can be one of the following: * invalid request body * dataset id was incorrect * edition was incorrect * an unpublished version of the dataset already exists 401: description: "Unauthorised to update version of dataset" 404: description: "Dataset series was not found for a dataset using the id and edition provided" 500: $ref: "#/responses/InternalError" /datasets/{id}/editions/{edition}/versions/{version}: post: tags: - "Private" summary: "Create a specific version" description: "Create a specific version for a dataset series. This will set the state of the version and dataset series to be associated." parameters: - $ref: "#/parameters/dataset_id" - $ref: "#/parameters/edition" - $ref: "#/parameters/version" - $ref: "#/parameters/new_version" - $ref: "#/parameters/is_latest" security: - {} - Authorization: [] responses: 201: description: "A json object containing a version" schema: $ref: "#/definitions/Version" 400: description: | Invalid request, reasons can be one of the following: * invalid request body * dataset id was incorrect * edition was incorrect * an unpublished version of the dataset already exists * is_latest parameter is not a valid boolean 401: description: "Unauthorised to update version of dataset" 404: description: "Dataset series was not found for a dataset using the id and edition provided" 409: description: "Version already exists" 500: $ref: "#/responses/InternalError" put: tags: - "Private" summary: "Update a version" description: "Update a version for an edition of a dataset, if the state is changed to associated or published, the parent documents(dataset and edition resources) will also be updated. A version can only be updated if the state is not published" parameters: - $ref: "#/parameters/dataset_id" - $ref: "#/parameters/edition" - $ref: "#/parameters/version" - $ref: "#/parameters/version_update" security: - Authorization: [] - Authorization: [] DownloadServiceAPIKey: [] responses: 200: description: "A json object containing a version" schema: $ref: "#/definitions/Version" 400: description: | Invalid request, reasons can be one of the following: * invalid request body * dataset id was incorrect * edition was incorrect 401: description: "Unauthorised to update version of dataset" 403: description: "Forbidden to overwrite version of dataset, already published" 404: description: "Version was not found for a dataset using the id and edition provided" 500: $ref: "#/responses/InternalError" get: tags: - "Public" summary: "Get a specific version" description: "Get a specific version of an edition of a dataset" parameters: - $ref: "#/parameters/edition" - $ref: "#/parameters/dataset_id" - $ref: "#/parameters/version" security: - {} - Authorization: [] responses: 200: description: "A json object containing the edition and version of a dataset" schema: $ref: "#/definitions/Version" headers: ETag: description: The RFC7232 ETag header field. Defines the unique entity tag for the current state of the resource. This is used for setting the `If-Match` and `If-None-Match` headers on subsequent requests. type: string Cache-Control: description: The RFC9111 Cache-Control header field for the response which instructs how to handle caching the resource. type: string 400: description: | Invalid request, reasons can be one of the following: * dataset id was incorrect * edition was incorrect 404: description: "No version was found for an edition of a dataset using the id, edition and version provided" 500: $ref: "#/responses/InternalError" delete: tags: - "Private" summary: "Delete a version" description: "detache/delete a version from a dataset. For CMD and Cantabular datasets, the version is `soft-deleted`. For static datasets, the version is `permanently deleted` from the versions collection." parameters: - $ref: "#/parameters/edition" - $ref: "#/parameters/dataset_id" - $ref: "#/parameters/version" security: - Authorization: [] responses: 200: description: "A json object containing the edition and version of a dataset. For CMD, Cantabular" schema: $ref: "#/definitions/Version" 204: description: "Version successfully deleted (no content). For static datasets" 400: description: | Invalid request, reasons can be one of the following: * dataset id was invalid 401: description: "Unauthorised to delete version of dataset" 403: description: "Forbidden – published static versions cannot be deleted" 404: description: "No version was found for an edition of a dataset using the id, edition and version provided" 405: description: "Requested method is not allowed" 500: $ref: "#/responses/InternalError" /datasets/{id}/editions/{edition}/versions/{version}/state: put: tags: - "Private" summary: "Update the state of a version" description: "Update the state of a version of a static dataset." parameters: - $ref: "#/parameters/dataset_id" - $ref: "#/parameters/edition" - $ref: "#/parameters/version" - description: "The new state of the version" required: true name: state in: body schema: type: object properties: state: $ref: "#/definitions/State" security: - Authorization: [] responses: 200: description: "State updated successfully" 400: description: "Bad Request due to invalid json in the request body" 404: description: "Dataset, edition or version not found" 500: $ref: "#/responses/InternalError" /datasets/{id}/editions/{edition}/versions/{version}/dimensions: get: tags: - "Public" summary: "Get a list of dimensions from a dataset (filterable and cantabular datasets only)" description: "Get all dimensions which are used in the dataset" parameters: - $ref: "#/parameters/edition" - $ref: "#/parameters/dataset_id" - $ref: "#/parameters/version" - $ref: "#/parameters/limit" - $ref: "#/parameters/offset" security: - {} - Authorization: [] responses: 200: description: "A json list of dimensions" schema: $ref: "#/definitions/Dimensions" headers: ETag: description: The RFC7232 ETag header field the of the resource, where the resource is the response to the specific query paramaters. This is used for setting the `If-None-Match` headers on subsequent requests to check for changes. type: string Cache-Control: description: The RFC9111 Cache-Control header field for the response which instructs how to handle caching the resource. type: string 400: description: | Invalid request, reasons can be one of the following: * dataset id was incorrect * edition was incorrect * version was incorrect 404: description: "No dimensions found for version of an edition of a dataset using the id, edition and version provided" 500: $ref: "#/responses/InternalError" /datasets/{id}/editions/{edition}/versions/{version}/dimensions/{dimension}/options: get: tags: - "Public" summary: "Get a list of options from a dimension (filterable and cantabular datasets only)" description: "Get a list of options which appear in this dimension and dataset. By default all options are returned, but a subset can be requested by providing offset and limit query parameters, or by providing the list of option IDs, only the IDs that are found will be returned." parameters: - $ref: "#/parameters/dimension" - $ref: "#/parameters/edition" - $ref: "#/parameters/dataset_id" - $ref: "#/parameters/version" - $ref: "#/parameters/limit" - $ref: "#/parameters/offset" - $ref: "#/parameters/ids" security: - {} - Authorization: [] responses: 200: description: "Json object containing all options for a dimension" schema: $ref: "#/definitions/DimensionOptions" headers: ETag: description: The RFC7232 ETag header field the of the resource, where the resource is the response to the specific query paramaters. This is used for setting the `If-None-Match` headers on subsequent requests to check for changes. type: string Cache-Control: description: The RFC9111 Cache-Control header field for the response which instructs how to handle caching the resource. type: string 400: description: | Invalid request, reasons can be one of the following: * dataset id was incorrect * edition was incorrect * version was incorrect * dimension was incorrect * query parameters incorrect offset provided * query parameters incorrect limit provided 404: description: "No dimension options were found for dimension" 500: $ref: "#/responses/InternalError" /datasets/{id}/editions/{edition}/versions/{version}/metadata: get: tags: - "Public" summary: "Get metadata for a version" description: "Get all metadata relevant to a version" parameters: - $ref: "#/parameters/edition" - $ref: "#/parameters/dataset_id" - $ref: "#/parameters/version" security: - {} - Authorization: [] responses: 200: description: "Json object containing all metadata for a version" schema: $ref: "#/definitions/Metadata" headers: ETag: description: The RFC7232 ETag header field. Defines the unique entity tag for the current state of the resource. This is used for setting the `If-Match` and `If-None-Match` headers on subsequent requests. type: string Cache-Control: description: The RFC9111 Cache-Control header field for the response which instructs how to handle caching the resource. type: string 400: description: | Invalid request, reasons can be one of the following: * dataset id was incorrect * edition was incorrect 404: description: "Version not found" 500: $ref: "#/responses/InternalError" put: tags: - "Private" summary: "Update metadata for a dataset and a version" description: "Update metadata for a dataset and a version. The editable metadata can be updated only if both the dataset and the version have a state of associated" parameters: - $ref: "#/parameters/dataset_id" - $ref: "#/parameters/edition" - $ref: "#/parameters/version" - $ref: "#/parameters/if_match" - $ref: "#/parameters/metadata_update" security: - Authorization: [] responses: 200: description: "The editable metadata has been updated" 400: description: | Invalid request, reasons can be one of the following: * invalid request body * version was incorrect 401: description: "Unauthorised to update metadata" 403: description: "Unable to update resource, expected resource to have a state of associated" 404: description: "Version was not found for a dataset using the id and edition provided" 409: description: "Instance does not match the expected eTag" 500: $ref: "#/responses/InternalError" /instances: get: tags: - "Private" summary: "Get instances" description: "Get a list of instances which has been paged" parameters: - $ref: "#/parameters/state" - $ref: "#/parameters/dataset" - $ref: "#/parameters/limit" - $ref: "#/parameters/offset" produces: - "application/json" security: - Authorization: [] responses: 200: description: "Return a list of instance state" schema: $ref: "#/definitions/Instances" headers: ETag: description: The RFC7232 ETag header field. Defines the unique entity tag for the current state of the resource. This is used for setting the `If-Match` and `If-None-Match` headers on subsequent requests. type: string Cache-Control: description: The RFC9111 Cache-Control header field for the response which instructs how to handle caching the resource. type: string 400: $ref: "#/responses/InvalidRequestError" 401: $ref: "#/responses/UnauthorisedError" 500: $ref: "#/responses/InternalError" post: tags: - "Private" summary: "Create an instance" description: | Create an instance which will be imported. To create an instance an import job id and href is required. This is to allow a link back to the import job parameters: - $ref: "#/parameters/newInstance" produces: - "application/json" security: - Authorization: [] responses: 201: description: "Successfully created instance" schema: $ref: "#/definitions/NewInstance" headers: ETag: type: string description: "Defines a unique instance resource version" 400: $ref: "#/responses/InvalidRequestError" 401: $ref: "#/responses/UnauthorisedError" 403: $ref: "#/responses/ForbiddenError" 500: $ref: "#/responses/InternalError" /instances/{instance_id}: get: tags: - "Private" summary: "Get an instance" description: "Get the current state of an instance, this includes all events which have happened." parameters: - $ref: "#/parameters/instance_id" - $ref: "#/parameters/if_match" produces: - "application/json" security: - Authorization: [] responses: 200: description: "Return a single instance state" schema: $ref: "#/definitions/Instance" headers: ETag: description: The RFC7232 ETag header field. Defines the unique entity tag for the current state of the resource. This is used for setting the `If-Match` and `If-None-Match` headers on subsequent requests. type: string Cache-Control: description: The RFC9111 Cache-Control header field for the response which instructs how to handle caching the resource. type: string 401: $ref: "#/responses/UnauthorisedError" 404: $ref: "#/responses/InstanceNotFound" 409: $ref: "#/responses/ConflictError" 500: $ref: "#/responses/InternalError" put: tags: - "Private" summary: "Update an instance" description: "Update an instance by providing an unique id and a set of properties to over write" parameters: - $ref: "#/parameters/instance_id" - $ref: "#/parameters/instance" - $ref: "#/parameters/if_match" produces: - "application/json" security: - Authorization: [] responses: 200: description: "The instance has been updated" headers: ETag: type: string description: "Defines a unique instance resource version" 400: $ref: "#/responses/InvalidRequestError" 401: $ref: "#/responses/UnauthorisedError" 403: $ref: "#/responses/ForbiddenError" 404: $ref: "#/responses/InstanceNotFound" 409: $ref: "#/responses/ConflictError" 500: $ref: "#/responses/InternalError" /instances/{instance_id}/dimensions: get: tags: - "Private" summary: "Get a list of dimensions for an instance" description: "Get all dimensions from an instance" parameters: - $ref: "#/parameters/instance_id" - $ref: "#/parameters/if_match" produces: - "application/json" security: - Authorization: [] responses: 200: description: "Return a list of dimensions" schema: type: array items: $ref: "#/definitions/DimensionOption" headers: ETag: description: The RFC7232 ETag header field. Defines the unique entity tag for the current state of the resource. This is used for setting the `If-Match` and `If-None-Match` headers on subsequent requests. type: string Cache-Control: description: The RFC9111 Cache-Control header field for the response which instructs how to handle caching the resource. type: string 400: $ref: "#/responses/InvalidRequestError" 401: $ref: "#/responses/UnauthorisedError" 403: $ref: "#/responses/ForbiddenError" 404: $ref: "#/responses/InstanceNotFound" 409: $ref: "#/responses/ConflictError" 500: $ref: "#/responses/InternalError" post: deprecated: true tags: - "Private" summary: "Create a dimension" description: "Create a new dimension which is related to an instance" parameters: - $ref: "#/parameters/instance_id" - $ref: "#/parameters/update_dimension_option_request" - $ref: "#/parameters/if_match" security: - Authorization: [] responses: 201: description: "Dimension was created" headers: ETag: type: string description: "Defines a unique instance resource version" 400: $ref: "#/responses/InvalidRequestError" 404: $ref: "#/responses/InstanceNotFound" 409: $ref: "#/responses/ConflictError" 500: $ref: "#/responses/InternalError" patch: tags: - "Private" summary: "Create one or more dimensions" description: "Create one or more dimensions which are related to an instance" parameters: - $ref: "#/parameters/instance_id" - $ref: "#/parameters/patch_dimensions" - $ref: "#/parameters/if_match" produces: - "application/json-patch+json" security: - Authorization: [] responses: 200: description: "All dimensions were successfully created" schema: $ref: "#/definitions/PatchDimensions" headers: ETag: type: string description: "Defines a unique instance resource version" 400: $ref: "#/responses/InvalidRequestError" 404: $ref: "#/responses/InstanceNotFound" 409: $ref: "#/responses/ConflictError" 500: $ref: "#/responses/InternalError" /instances/{instance_id}/dimensions/{dimension}: put: tags: - "Private" summary: "Update dimension" description: "Update the label and/or description of a dimension within an instance, by providing dimension name and properties to over write" parameters: - $ref: "#/parameters/instance_id" - $ref: "#/parameters/dimension" - $ref: "#/parameters/update_dimension" - $ref: "#/parameters/if_match" security: - Authorization: [] responses: 200: description: "The instance has been updated" headers: ETag: type: string description: "Defines a unique instance resource version" 400: $ref: "#/responses/InvalidRequestError" 401: $ref: "#/responses/UnauthorisedError" 403: $ref: "#/responses/ForbiddenError" 404: $ref: "#/responses/InstanceNotFound" 409: $ref: "#/responses/ConflictError" 500: $ref: "#/responses/InternalError" /instances/{instance_id}/dimensions/{dimension}/options: get: tags: - "Private" summary: "Get a list of options for a dimension" description: "Get all unique options from a dimension" parameters: - $ref: "#/parameters/instance_id" - $ref: "#/parameters/dimension" - $ref: "#/parameters/if_match" produces: - "application/json" security: - Authorization: [] responses: 200: description: "Return a list of unique options" schema: type: object properties: dimension: description: "The name of the dimension" type: string options: description: "A list of all unique options within a dimension" type: array items: type: string headers: ETag: description: The RFC7232 ETag header field. Defines the unique entity tag for the current state of the resource. This is used for setting the `If-Match` and `If-None-Match` headers on subsequent requests. type: string Cache-Control: description: The RFC9111 Cache-Control header field for the response which instructs how to handle caching the resource. type: string 400: $ref: "#/responses/InvalidRequestError" 401: $ref: "#/responses/UnauthorisedError" 403: $ref: "#/responses/ForbiddenError" 404: description: "dimension does not match any dimensions within the instance" 409: $ref: "#/responses/ConflictError" 500: $ref: "#/responses/InternalError" /instances/{instance_id}/events: post: tags: - "Private" summary: "Add an event to an instance" description: | Add a new event into an instance. Events can be for information or error messages. Each event must contain a type of event (Info or Error), a message to explain the event, time of the event and finally the message offset in kafka parameters: - $ref: "#/parameters/instance_id" - $ref: "#/parameters/event" - $ref: "#/parameters/if_match" security: - Authorization: [] responses: 201: description: "The event was added to the instance" headers: ETag: type: string description: "Defines a unique instance resource version" 400: $ref: "#/responses/InvalidRequestError" 401: $ref: "#/responses/UnauthorisedError" 404: description: "InstanceId does not match any instances" 409: $ref: "#/responses/ConflictError" 500: $ref: "#/responses/InternalError" /instances/{instance_id}/inserted_observations/{inserted_observations}: put: tags: - "Private" summary: "Increment the inserted observation count" description: "This will add to the number already store in the api" parameters: - $ref: "#/parameters/instance_id" - $ref: "#/parameters/inserted_observations" - $ref: "#/parameters/if_match" security: - Authorization: [] responses: 200: description: "Added value to inserted observation" headers: ETag: type: string description: "Defines a unique instance resource version" 400: $ref: "#/responses/InvalidRequestError" 401: $ref: "#/responses/UnauthorisedError" 404: description: "InstanceId does not match any instances" 409: $ref: "#/responses/ConflictError" 500: $ref: "#/responses/InternalError" /instances/{instance_id}/import_tasks: put: tags: - "Private" summary: "Update import tasks for an instance" description: "The instance import process involves multiple tasks. This endpoint updates the state of an import task." parameters: - $ref: "#/parameters/instance_id" - $ref: "#/parameters/import_tasks" - $ref: "#/parameters/if_match" security: - Authorization: [] responses: 200: description: "Updated the state of the import task" headers: ETag: type: string description: "Defines a unique instance resource version" 400: $ref: "#/responses/InvalidRequestError" 401: $ref: "#/responses/UnauthorisedError" 404: description: "InstanceId does not match any instances" 409: $ref: "#/responses/ConflictError" 500: $ref: "#/responses/InternalError" /instances/{instance_id}/dimensions/{dimension}/options/{option}: patch: tags: - "Private" summary: "Modify a dimension option for an instance" description: | Modify a dimension option for an instance by setting values for node_id or order parameters: - $ref: "#/parameters/instance_id" - $ref: "#/parameters/dimension" - $ref: "#/parameters/option" - $ref: "#/parameters/patch_options" - $ref: "#/parameters/if_match" produces: - "application/json-patch+json" security: - Authorization: [] responses: 200: description: "The dimension option was modified and the successfully applied patch operations are returned" schema: $ref: "#/definitions/PatchOptions" headers: ETag: type: string description: "Defines a unique instance resource version" 400: $ref: "#/responses/InvalidRequestError" 401: $ref: "#/responses/UnauthorisedError" 403: $ref: "#/responses/ForbiddenError" 404: description: "InstanceId does not match any instances" 409: $ref: "#/responses/ConflictError" 500: $ref: "#/responses/InternalError" /instances/{instance_id}/dimensions/{dimension}/options/{option}/node_id/{node_id}: put: deprecated: true tags: - "Private" summary: "Update a dimension with the node_id" description: | Update the dimension with a nodeId parameters: - $ref: "#/parameters/instance_id" - $ref: "#/parameters/dimension" - $ref: "#/parameters/node_id" - $ref: "#/parameters/option" - $ref: "#/parameters/if_match" produces: - "application/json" security: - Authorization: [] responses: 200: description: "Updated the dimension with the nodeId" headers: ETag: type: string description: "Defines a unique instance resource version" 400: $ref: "#/responses/InvalidRequestError" 401: $ref: "#/responses/UnauthorisedError" 403: $ref: "#/responses/ForbiddenError" 404: description: "InstanceId does not match any instances" 409: $ref: "#/responses/ConflictError" 500: $ref: "#/responses/InternalError" responses: ConflictError: description: "Failed to process the request due to a conflict" ForbiddenError: description: "The request is forbidden" InstanceNotFound: description: "The instance was not found" InternalError: description: "Failed to process the request due to an internal error" InvalidRequestError: description: "Failed to process the request due to invalid request" UnauthorisedError: description: "The token provided is unauthorised to carry out this operation" definitions: Alert: description: "Important notice relating to a version of a dataset" type: object required: - date - description - type properties: date: description: "The date and time of publication of the version" type: string format: date-time description: description: "Detail of what a user needs to be aware of for this dataset" type: string example: "This is a description of the changes made as part of the correction or other important notice about this version." type: description: | 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. type: string enum: - alert - correction example: "correction" Codelist: type: object properties: href: description: "A link to the codelist corresponding to this dimension" type: string id: description: "The codelist id corresponding to this dimension" type: string name: description: "The dimension name" type: string description: description: "The dimension description" type: string label: description: "A human readable label for dimension" type: string CollectionID: description: | **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." type: string example: 666c06bc09d337ab9d164c82f8f383c081a4e38cbd91b79d4a23ea0025fecb3f Contact: description: "Statistical point of contact for the dataset." type: object required: - name - email properties: email: description: "Email address to contact the statistician or statistician group responsible for the dataset." type: string format: email example: "example@ons.gov.uk" pattern: "@ons\\.gov\\.uk$" name: description: "The name of the statistician or statistician group contact point responsible for the dataset." type: string example: "Expert Statistical Team" telephone: description: "Telephone number to contact the statistician or statistician group responsible for the dataset." type: string example: "+44 1234 111111" pattern: "^\\+44 (\\(0\\))?[1-9](\\d ?){8,10}$" DatasetID: description: | The unique identifier for a dataset. The dataset ID cannot be changed once the series is first published. example: "my-dataset" type: string minLength: 1 maxLength: 100 pattern: "^[a-z0-9]+(-[a-z0-9]+)*$" Datasets: description: "A list of datasets" type: object allOf: - $ref: "#/definitions/PaginationFields" - type: object properties: items: type: array items: $ref: "#/definitions/Dataset" Dataset: description: "The dataset" type: object required: - id - contacts - description - license - title - type - topics properties: id: $ref: "#/definitions/DatasetID" canonical_topic: description: | **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. type: string example: "7779" collection_id: $ref: "#/definitions/CollectionID" contacts: description: "A list containing contact details of statisticians for a dataset" type: array minItems: 1 items: $ref: "#/definitions/Contact" description: description: "A description for a dataset" type: string example: "This dataset contains some very interesting data about the UK." minLength: 50 maxLength: 5000 is_based_on: $ref: "#/definitions/IsBasedOn" is_migration: description: "Indicates whether this dataset series was created as part of a dataset migration" type: boolean keywords: description: "A list of keywords for a dataset" type: array items: type: "string" example: "Inflation" last_updated: $ref: "#/definitions/LastUpdated" license: description: "The license the dataset is released under." type: string default: "Open Government Licence v3.0" links: $ref: "#/definitions/DatasetLinks" methodologies: description: "A list of methodologies for the dataset." type: array items: $ref: "#/definitions/RelatedLink" national_statistic: description: | **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. type: boolean next_release: $ref: "#/definitions/NextRelease" publications: description: "A list of publications related to this dataset." type: array items: $ref: "#/definitions/RelatedLink" publishers: description: A list of the publishers for the dataset. type: array minItems: 1 items: $ref: "#/definitions/Publisher" default: - name: Office for National Statistics href: https://www.ons.gov.uk qmi: $ref: "#/definitions/QMILink" related_datasets: description: "A list of other datasets related to this dataset." type: array items: $ref: "#/definitions/RelatedLink" related_content: description: "A list of website content related to this dataset." type: array items: $ref: "#/definitions/RelatedLink" release_frequency: description: "The release frequency of a dataset" type: string example: "Monthly" state: $ref: "#/definitions/State" subtopics: description: | **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. type: array items: type: "string" example: "7755" survey: description: "The name of the survey the dataset was created from." type: string example: "census" title: description: "The title of the dataset" example: "Consumer Prices Index" type: string minLength: 1 topics: description: "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: array minItems: 1 items: type: "string" example: ["7779", "7755"] type: $ref: "#/definitions/DatasetType" unit_of_measure: description: "The unit of measure for the dataset observations" type: string example: "Number of people" LastUpdated: description: 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. type: string format: date-time readOnly: true NextRelease: description: "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." type: string example: "To be announced" DatasetType: description: | 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. type: string enum: - filterable - cantabular_flexible_table - cantabular_multivariate_table - static default: "filterable" example: "static" IsBasedOn: 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" DatasetEdition: description: "A single dataset edition" type: object required: - dataset_id - title - description - edition - edition_title - latest_version - release_date - state properties: dataset_id: $ref: "#/definitions/DatasetID" title: description: "The title of the dataset" type: string example: "Consumer Prices Index" minLength: 1 description: description: "The description of the dataset" type: string example: "CPIH is the most comprehensive measure of inflation. It extends CPI to include a measure of the costs associated with owning, maintaining and living in one's own home, known as owner occupiers' housing costs (OOH), along with council tax. This dataset provides CPIH time series (2005 to latest published month), allowing users to customise their own selection, view or download." minLength: 1 edition: $ref: "#/definitions/EditionID" edition_title: description: "The human readable title of the edition" type: string example: "January 2025" latest_version: $ref: "#/definitions/LatestVersionLink" release_date: description: "The release date of the this version of the dataset edition" type: string format: date-time state: $ref: "#/definitions/State" Dimension: description: "A single dimension within a dataset" type: object properties: description: 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: description: "" 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: $ref: "#/definitions/OptionsLink" version: $ref: "#/definitions/VersionLink" number_of_options: description: "The number of options available for this dimension" type: integer variable: description: "The variable name (census datasets only)" type: string Dimensions: description: "List of dimensions for a specific dataset version." type: object allOf: - $ref: "#/definitions/PaginationFields" - type: object properties: items: type: array items: $ref: "#/definitions/Dimension" DimensionOptions: description: "A list of options for a specific dimension." type: object allOf: - $ref: "#/definitions/PaginationFields" - type: object properties: items: type: array items: $ref: "#/definitions/DimensionOption" DimensionOption: type: object properties: dimension: description: "The name of the dimension" type: string instance_id: description: "The unique identifier for the instance in which this dimension option is associated to" type: string label: description: "A label given to a dimension option" type: string links: description: "A object with all resources related to a dimension option" type: object properties: code: description: "A link to the code of the dimension for this option" type: object properties: href: description: "The url of the code that refers to the dimension for this option" type: string id: description: "The id of the code that refers to the dimension for this option" type: string code_list: description: "A link to the code list the dimension for this option belongs to" type: object properties: href: description: "The url of the code list that the dimension for this option belongs to" type: string id: description: "The id of the code list that the dimension for this option belongs to" type: string version: description: "A link to the version of the dataset the option belongs to" readOnly: true type: object properties: href: description: "The href of the version that this option belongs to" type: string id: description: "The id of the version that this option belongs to" type: string node_id: description: "The id of the node" type: string option: description: "An option for a dimension" type: string AuditEvent: description: Details of a specific change event forming part of the change and audit log for a dataset, edition, or version. type: object readOnly: true required: - requested_by - action - resource - data properties: created_at: description: The date and time the event occurred. type: string format: date-time requested_by: description: The user who made the request. type: object required: - id properties: id: description: The ID of the user. type: string example: 0889d599-3f0e-4564-9d6e-9455a6b73da7 email: description: The email of the user. This is only populated if the user is a human user. type: string format: email example: publisher@ons.gov.uk action: description: The action taken by the user. type: string enum: - CREATE - READ - UPDATE - DELETE resource: description: The path of the API resource that was called. type: string example: /datasets/cpi/editions/march/versions/1 data: description: | The state of the resource following a change action, or the state of the record when the user viewed it. This will be either a `Dataset` or `Version` object, but as OpenAPI 2.0 does not support `oneOf`, no schema is shown. type: object example: edition: march edition_title: March 2025 release_date: 2025-01-27T07:00:00.000Z state: published last_updated: 2025-01-26T07:00:00.000Z version: 1 type: static e_tag: ae798cd1893778920d74e1bb185b215fce309708 quality_designation: accredited-official links: dataset: href: /datasets/cpi id: cpi edition: href: /datasets/cpi/editions/march id: march self: href: /datasets/cpi/editions/march/versions/1 version: href: /datasets/cpi/editions/march/versions/1, id: 1 distributions: [{"title" : "Full Dataset (CSV)", "format" : "csv", "media_type" : "text/csv", "download_url" : "/datasets/RM086/editions/march/thedownloadfile.csv", "byte_size" : 4300000}] AuditEventsList: description: "The list of change events which form the change and audit log for a dataset or edition." type: object readOnly: true allOf: - $ref: "#/definitions/PaginationFields" - type: object properties: items: type: array items: $ref: "#/definitions/AuditEvent" PatchOptions: description: "A list of operations to patch a dimension option. Can only handle adding values for /node_id and /order. Each element in the array is processed in sequential order." type: array items: type: object description: "Item containing all necessary information to make a single operation on the resource." properties: op: description: | The operation to be made on path. * add - Sets the value for the provided path type: string enum: [add] path: description: "Path to value that needs to be operated on." type: string example: "/node_id" enum: [/node_id, /order] value: description: "A value that will be set for the provided path. /node_id accepts string values, and /order accepts integer values." example: "node_123" PatchDimensions: description: "A list of operations to patch dimensions. Can only handle adding lists of dimension values, and modifying order and node_id values for existing dimension options. The patch operations are executed in bulk to improve performance, and they are idempotent. If at least one of the provided dimensions and/or options in a patch path cannot be matched against existing dimension options, the request will fail with 404." type: array items: type: object description: "Item containing all necessary information to make a single operation on the resource." properties: op: description: | The operation to be made on path. * add - Sets the value for the provided path type: string enum: ["add"] path: description: "Path to value that needs to be operated on." type: string example: "/-" enum: ["/-", "/{dimension}/options/{option}/order", "/{dimension}/options/{option}/node_id"] value: description: "A list of dimensions that will be added to the instance." example: '[{"dimension": "dim1", "option": "op1"}, {"dimension": "dim1", "option": "op2"}, {"op": "add", "path": "/dim1/options/op1/order", "value": 3}, {"op": "add", "path": "/dim1/options/op2/node_id", "value": "node123"}]' DownloadObject: description: "Object containing information of a downloadable file" type: object properties: href: description: "The URL to the generated file" type: string example: https://download.ons.gov.uk/my-dataset-download.csv size: description: "The size of the file in bytes" type: string example: "466807" EditionID: description: | 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. example: july-september-2017 type: string minLength: 1 maxLength: 100 pattern: "^[a-z0-9]+(-[a-z0-9]+)*$" Editions: description: "A list of editions of a dataset." type: object allOf: - $ref: "#/definitions/PaginationFields" - type: object properties: items: type: array items: $ref: "#/definitions/Version" Event: type: object properties: message: description: "A description of the event" type: string message_offset: description: "The kafka message offset (Used to locate the kafka message)" type: string time: description: "The time of the event in ISO 8601 format" type: string type: description: | The type of event, this can be; * Info - for an information event * Error - for an error event type: string ImportTasks: type: object properties: build_hierarchies: type: array items: type: object properties: code_list_id: description: "The ID of the codelist that this hierarchy represents" type: string dimension_name: description: "The name of the dimension the hierarchy represents" type: string state: description: "The state of the import observations task" type: string build_search_indexes: type: array items: type: object properties: dimension_name: description: "The name of the dimension the search index represents" type: string state: description: "The state of the import observations task" type: string import_observations: type: object properties: state: description: "The state of the import observations task" type: string total_inserted_observations: description: "The number of inserted observations in this instance" type: integer Instance: type: object properties: alerts: description: "A list of alerts against an instance" readOnly: true type: array items: $ref: "#/definitions/Alert" id: description: "A unique id for an instance" readOnly: true type: string collection_id: $ref: "#/definitions/CollectionID" dimensions: description: "A list of codelists for each dimension of this instance" type: array items: $ref: "#/definitions/Codelist" downloads: description: "A selection of download objects containing information of downloadable files." type: object properties: csv: $ref: "#/definitions/DownloadObject" xls: $ref: "#/definitions/DownloadObject" edition: $ref: "#/definitions/EditionID" events: description: "A list of events took place for this job" readOnly: true type: array items: $ref: "#/definitions/Event" headers: description: "The header information from a V4 file" type: array items: type: string import_tasks: $ref: "#/definitions/ImportTasks" last_updated: description: "The last time an event happened" readOnly: true type: string links: type: object properties: dataset: description: "An object describing the ID and URL for a dataset which is associated with this instance" readOnly: true type: object properties: href: description: "The URL for the dataset associated with this instance" example: "https://api.beta.ons.gov.uk/v1/datasets/my-dataset" type: string id: $ref: "#/definitions/DatasetID" dimensions: description: "An object describing the URL for the dimensions which are associated with this instance" readOnly: true type: object properties: href: description: "The URL for a list of dimensions associated with this instance" example: "https://api.beta.ons.gov.uk/v1/datasets/my-dataset/editions/july-september-2017/versions/1/dimensions" type: string edition: description: "An object describing the ID and URL for the dataset edition that is associated with this instance" readOnly: true type: object properties: href: description: "The URL for the dataset edition associated with this instance" example: "https://api.beta.ons.gov.uk/v1/datasets/my-dataset/editions/july-september-2017" type: string id: $ref: "#/definitions/EditionID" job: description: "An object describing the ID and URL of the job containing this instance" readOnly: true required: ["id", "href"] type: object properties: href: description: "The URL for the job containing this instance" example: "https://api.beta.ons.gov.uk/v1/jobs/042e216a-7822-4fa0-a3d6-e3f5248ffc35" type: string id: description: "The ID of the job containing this instance" example: 042e216a-7822-4fa0-a3d6-e3f5248ffc35 type: string self: description: "An object describing the ID and URL for a dataset which is associated with this instance" readOnly: true type: object properties: href: description: "The URL for this resource" example: "https://api.beta.ons.gov.uk/v1/instances/45c4669b-3ae9-4ba7-b690-87e890a1c67f" type: string version: description: "An object describing the ID and URL of the dataset version associated with this instance" readOnly: true type: object properties: href: description: "The URL for the dataset version associated with this instance" example: "https://api.beta.ons.gov.uk/v1/dataset/my-dataset/edition/july-september-2017/versions/1" type: string id: description: "The ID of the dataset version associated with this instance" example: "1" type: string release_date: description: "The release date of this version of the dataset" type: string format: date-time state: $ref: "#/definitions/State" total_observations: description: "The number of observations in this instance" type: integer version: description: "The dataset version number that this instance is associated with, this will only be set once the state has been updated to `edition-confirmed`" readOnly: true type: integer Instances: description: "A list of instance resources, if query parameter state is set return all instances with that state" type: object allOf: - $ref: "#/definitions/PaginationFields" - type: object properties: items: type: array items: $ref: "#/definitions/Instance" LatestChange: 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 example: 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: description: "The title of the change that has occurred between versions" type: string example: "Data Suppression Changes" Metadata: description: "An object containing all metadata information against a version" type: object properties: alerts: description: "A list of alerts, for example corrections after the resource has been published" type: array items: $ref: "#/definitions/Alert" canonical_topic: description: | **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. type: string example: "7779" contacts: description: "A list containing contact details of statisticians for a dataset" type: array minItems: 1 items: $ref: "#/definitions/Contact" dataset_id: allOf: - readOnly: true - $ref: "#/definitions/DatasetID" dataset_links: $ref: "#/definitions/DatasetLinks" description: description: "A description for a dataset" type: string example: "This dataset contains some very interesting data about the UK." minLength: 50 maxLength: 5000 dimensions: description: "A list of codelists for each dimension of this version" type: array items: $ref: "#/definitions/Dimension" distribution: description: | **Deprecated:** This field is being deprecated. Use `distributions` for list of formats in which the dataset can be accessed. A list of media types that the version data of an edition of a dataset can be accessed type: array readOnly: true items: type: string example: csv distributions: description: A list of representations of the dataset available and how to access them. type: array readOnly: true minItems: 1 items: $ref: "#/definitions/Distribution" downloads: allOf: - readOnly: true - $ref: "#/definitions/VersionDownloads" edition: allOf: - readOnly: true - $ref: "#/definitions/EditionID" edition_title: description: The human readable title of the edition. type: string example: July to September 2017 headers: description: "A list of headers for a census dataset" type: array readOnly: true items: type: "string" example: - cantabular_table - ltla - ethnic_group_tb_8a is_migration: description: "Indicates whether this version was created as part of a dataset migration" type: boolean keywords: description: "A list of keywords for a dataset" type: array items: type: "string" example: "Inflation" last_updated: $ref: "#/definitions/LastUpdated" 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: $ref: "#/definitions/LatestChange" license: description: "The license the dataset is released under." type: string default: "Open Government Licence v3.0" links: $ref: "#/definitions/MetadataLinks" methodologies: description: "A list of methodologies for the dataset." type: array items: $ref: "#/definitions/RelatedLink" national_statistic: description: | **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. type: boolean next_release: $ref: "#/definitions/NextRelease" publications: description: "A list of publications related to this dataset." type: array items: $ref: "#/definitions/RelatedLink" publishers: description: A list of the publishers for the dataset. type: array items: $ref: "#/definitions/Publisher" state: $ref: "#/definitions/State" qmi: $ref: "#/definitions/QMILink" quality_designation: description: | The official statistics quality designation level of this dataset version. Possible quality designations: * `accredited-official` * `official` * `official-in-development` * `no-accreditation` type: string enum: - accredited-official - official - official-in-development - no-accreditation related_content: description: "A list of website content related to this dataset." type: array items: $ref: "#/definitions/RelatedLink" related_datasets: description: "A list of other datasets related to this dataset." type: array items: $ref: "#/definitions/RelatedLink" release_date: description: "The release date of this version of the dataset" type: string format: date-time release_frequency: description: "The release frequency of a dataset" type: string example: "Monthly" subtopics: description: | **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. type: array items: type: "string" example: "7755" survey: description: "The name of the survey the dataset was created from." type: string example: census title: description: "The title of the dataset" example: "Consumer Prices Index" type: string topics: description: "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: array minItems: 1 items: type: "string" example: ["7779", "7755"] type: allOf: - readOnly: true - $ref: "#/definitions/DatasetType" unit_of_measure: description: "The unit of measure for the dataset observations" type: string example: "Number of people" usage_notes: description: "A list of usage notes relating to the dataset" type: array items: $ref: "#/definitions/UsageNote" version: description: "A number identifying the version for an edition from a dataset" example: 1 readOnly: true type: integer NewDatasetResponse: description: "A model for the response body when creating a new dataset" type: object properties: id: description: "An unique database id for a dataset" example: "DE3BC0B6-D6C4-4E20-917E-95D7EA8C91DC" type: string current: allOf: - type: object properties: collection_id: $ref: "#/definitions/CollectionID" type: $ref: "#/definitions/DatasetType" - $ref: "#/definitions/Dataset" next: allOf: - type: object properties: collection_id: $ref: "#/definitions/CollectionID" type: $ref: "#/definitions/DatasetType" - $ref: "#/definitions/Dataset" NewInstance: description: "A model for the request and response body for creating a new instance" type: object properties: dimensions: description: "A list of codelists for each dimension of this instance" type: array items: $ref: "#/definitions/Codelist" id: description: "A unique id for an instance" readOnly: true type: string import_tasks: $ref: "#/definitions/ImportTasks" links: type: object readOnly: true properties: dataset: description: "An object describing the ID and URL for a dataset which is associated with this instance" type: object properties: href: description: "The URL for the dataset associated with this instance" example: "https://api.beta.ons.gov.uk/v1/datasets/my-dataset" type: string id: $ref: "#/definitions/DatasetID" job: description: "An object describing the ID and URL of the job containing this instance" required: ["id", "href"] type: object properties: href: description: "The URL for the job containing this instance" example: "https://api.beta.ons.gov.uk/v1/jobs/042e216a-7822-4fa0-a3d6-e3f5248ffc35" type: string id: description: "The ID of the job containing this instance" example: 042e216a-7822-4fa0-a3d6-e3f5248ffc35 type: string self: description: "An object describing the ID and URL for a dataset which is associated with this instance" readOnly: true type: object properties: href: description: "The URL for this resource" example: "https://api.beta.ons.gov.uk/v1/instances/45c4669b-3ae9-4ba7-b690-87e890a1c67f" type: string state: $ref: "#/definitions/State" Publisher: description: "The publisher of the dataset" type: object required: - name - href properties: name: description: "The name of the publisher" type: string minLength: 1 default: Office for National Statistics href: description: "A link to the publishers homepage" type: string minLength: 1 format: url default: "https://www.ons.gov.uk" State: description: | 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: string example: published enum: - created - completed - failed - edition-confirmed - associated - published UpdateDatasetResponse: description: "A model for the response body when creating a new dataset" type: object properties: id: description: "An unique database ID for a dataset" example: "DE3BC0B6-D6C4-4E20-917E-95D7EA8C91DC" type: string current: allOf: - type: object properties: collection_id: $ref: "#/definitions/CollectionID" - $ref: "#/definitions/Dataset" next: allOf: - type: object properties: collection_id: $ref: "#/definitions/CollectionID" - $ref: "#/definitions/Dataset" UpdateDimensionOptionRequest: description: "A cached dimension. (Only used by the Private API)" type: object properties: code: description: "" type: string codelist: description: "" type: string dimension: description: "The name of the dimension" type: string instance_id: description: "The unique identifier for the instance in which this dimension option is associated to" type: string label: description: "The label for a option" type: string option: description: "The option of the dimension" type: string order: description: "The numerical order for the dimension option" type: integer UpdateDownloadObject: 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 public: description: "The URL to a public-accessible download" type: string private: description: "The URL to a non public-accessible download" type: string UpdateInstanceDimension: description: "Possible fields to be updated against a dimension for an instance resource" type: object properties: description: description: "The dimension description" type: string label: description: "A human readable label for dimension" type: string UsageNote: description: Essential usage information a user needs to be aware of when interpreting the data. type: object required: - title - note properties: title: description: The title of the usage note. type: string example: Data Suppression note: description: The usage note text. type: string example: 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. Versions: description: "A list of version history for a specific dataset edition." type: object allOf: - $ref: "#/definitions/PaginationFields" - type: object properties: items: type: array items: $ref: "#/definitions/Version" Version: description: "An object containing information about published datasets from the ONS" required: - distributions - release_date - edition_title type: object properties: alerts: description: "A list of alerts, for example corrections after the resource has been published" type: array items: $ref: "#/definitions/Alert" collection_id: $ref: "#/definitions/CollectionID" dataset_id: allOf: - readOnly: true - $ref: "#/definitions/DatasetID" dimensions: description: "A list of codelists for each dimension of this version" type: array readOnly: true items: $ref: "#/definitions/Dimension" distributions: description: A list of representations of the dataset available and how to access them. type: array minItems: 1 items: $ref: "#/definitions/Distribution" downloads: allOf: - readOnly: true - $ref: "#/definitions/VersionDownloads" edition: allOf: - readOnly: true - $ref: "#/definitions/EditionID" edition_title: description: The human readable title of the edition. type: string minLength: 1 example: July to September 2017 is_based_on: $ref: "#/definitions/IsBasedOn" is_migration: description: "Indicates whether this version was created as part of a dataset migration" type: boolean last_updated: $ref: "#/definitions/LastUpdated" 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: $ref: "#/definitions/LatestChange" links: $ref: "#/definitions/VersionLinks" lowest_geography: description: | 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 type: string enum: - oa - lsoa - msoa - wpc - ltla - rgn quality_designation: description: | The official statistics quality designation level of this dataset version. Possible quality designations: * `accredited-official` * `official` * `official-in-development` * `no-accreditation` type: string enum: - accredited-official - official - official-in-development - no-accreditation related_content: description: "A list of website content related to this version." type: array items: $ref: "#/definitions/RelatedLink" release_date: description: "The release date of this version of the dataset" type: string format: date-time state: $ref: "#/definitions/State" type: readOnly: true allOf: - $ref: "#/definitions/DatasetType" usage_notes: description: "A list of usage notes relating to the dataset" type: array items: $ref: "#/definitions/UsageNote" version: description: "A number identifying the version for an edition from a dataset" example: 1 readOnly: true type: integer VersionDownloads: description: | **Deprecated:** These fields have been deprecated and replaced by the `distributions` list. A selection of download objects containing information of downloadable files. type: object properties: csv: $ref: "#/definitions/DownloadObject" csvw: allOf: - readOnly: true - $ref: "#/definitions/DownloadObject" txt: allOf: - readOnly: true - $ref: "#/definitions/DownloadObject" xls: $ref: "#/definitions/DownloadObject" example: 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" Distribution: description: The details of specific representation of a dataset and how to access it. type: object required: - title - format - download_url properties: title: description: The title or label of the distribution. type: string minLength: 1 example: Full Dataset (CSV) download_url: description: URL to directly download a file for the distribution in the specified format. type: string format: url minLength: 1 pattern: "^(/.+|https://[^/]+\\.ons\\.gov\\.uk/.+)" example: https://download.ons.gov.uk/my-dataset-download.csv byte_size: description: The size in bytes of the download file referenced by `download_url`. type: integer minimum: 0 example: 4300000 readOnly: true format: description: | The format for the download file referenced by `download_url`. Formats supported: * `csv` * `sdmx` * `xls` * `xlsx` * `csdb` type: string enum: - csv - sdmx - xls - xlsx - csdb media_type: description: | 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) type: string readOnly: true enum: - text/csv - application/vnd.sdmx.structurespecificdata+xml - application/vnd.ms-excel - application/vnd.openxmlformats-officedocument.spreadsheetml.sheet - text/plain # Link objects DatasetLinks: description: "Navigational links related to the dataset resource to aid in API navigation." type: object readOnly: true properties: editions: readOnly: true type: object properties: href: description: "A URL to all editions for this dataset" type: string example: "https://api.beta.ons.gov.uk/v1/datasets/my-dataset/editions" latest_version: $ref: "#/definitions/LatestVersionLink" latest_edition: description: "An object containing a link to the latest edition of the dataset." type: object readOnly: true properties: href: description: "A link to the latest edition of the dataset." type: string example: "https://api.beta.ons.gov.uk/v1/datasets/my-dataset/editions/july-september-2017" self: description: "A link to this resource" readOnly: true type: object properties: href: description: "A URL to this resource" type: string example: "https://api.beta.ons.gov.uk/v1/datasets/my-dataset" taxonomy: description: "The taxonomy path of the dataset's canonical topic." type: object readOnly: true properties: href: description: | **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. type: string example: https://www.ons.gov.uk/theme/topic MetadataLinks: description: "A list of links related to this resource" readOnly: true type: object properties: self: description: "A link to this resource" readOnly: true type: object properties: href: description: "A URL to this resource" type: string example: "https://api.beta.ons.gov.uk/v1/datasets/my-dataset/editions/july-september-2017/versions/5/metadata" version: $ref: "#/definitions/VersionLink" website_version: description: "A link to the location of this version of the dataset on the web" type: object readOnly: true properties: href: description: "The uri to the location of this version of the dataset on the web" type: string example: "https://www.ons.gov.uk/datasets/my-dataset/editions/july-september-2017/versions/5" VersionLinks: description: "A list of links related to this resource" type: object readOnly: true properties: dataset: $ref: "#/definitions/DatasetLink" dimensions: readOnly: true type: object properties: href: description: "A URL to list dimensions for this version" example: "https://api.beta.ons.gov.uk/v1/datasets/my-dataset/editions/july-september-2017/versions/5/dimensions" type: string edition: $ref: "#/definitions/EditionLink" self: description: "A link to this resource" readOnly: true type: object properties: href: description: "A URL to this resource" type: string example: "https://api.beta.ons.gov.uk/v1/datasets/my-dataset/editions/july-september-2017/versions/5" web_page: description: "A link to the location of this version of the dataset on the web" readOnly: true type: object properties: href: description: "The uri to the location of this version of the dataset on the web" type: string example: "https://www.ons.gov.uk/businessindustryandtrade/datasets/my-dataset/editions/july-september-2017/versions/5" versions: type: object readOnly: true properties: href: description: "A URL to all versions for an edition of a dataset" example: "https://api.beta.ons.gov.uk/v1/datasets/my-dataset/editions/july-september-2017/versions" type: string DatasetLink: description: "An object containing the dataset id and link" readOnly: true type: object properties: href: description: "A URL to the parent dataset for this resource" example: "https://api.beta.ons.gov.uk/v1/datasets/my-dataset" type: string id: $ref: "#/definitions/DatasetID" EditionLink: description: "An object containing the edition and link" readOnly: true type: object properties: href: description: "A URL to the dataset edition for a version" example: "https://api.beta.ons.gov.uk/v1/datasets/my-datasets/editions/july-september-2017" type: string id: description: "The unique id for the dataset edition for a version" type: string example: "july-september-2017" LatestVersionLink: description: "An object containing the latest version id and link" type: object readOnly: true properties: href: description: "A link to the latest version and edition of the dataset" example: "https://api.beta.ons.gov.uk/v1/datasets/my-dataset/editions/july-september-2017/versions/5" type: string id: description: "The unique id for the latest version of a dataset" type: "string" example: "5" MetadataLink: description: "The version metadata that is associated with this resource" type: object readOnly: true properties: href: description: "A URL for the version metadata this resource relates to" type: string OptionsLink: description: "A list of links related to this dimension" type: object readOnly: true properties: href: description: "A URL to a list of options for this dimension" type: string VersionLink: description: "The dataset version this resource belongs to" type: object readOnly: true properties: href: description: "A URL to the version this resource relates to" type: string example: "https://api.beta.ons.gov.uk/v1/datasets/my-dataset/editions/july-september-2017/versions/5" id: description: "The version number this resource relates to" type: string example: "5" RelatedLink: type: object required: - href - title properties: href: description: "The url of the linked item." type: string example: "https://www.ons.gov.uk/my-related-page" format: url pattern: "^(/.+|https://[^/]+\\.ons\\.gov\\.uk/.+)" title: description: "The title of the linked item." type: string minLength: 1 example: "Related Link Title" description: description: "The description of the linked item." type: string example: "This is a description of the linked resource." QMILink: type: object required: - href properties: href: description: "The url to the quality and methodology information sheet for the dataset." type: string format: url pattern: "^(/.+|https://[^/]+\\.ons\\.gov\\.uk/.+)" example: "https://www.ons.gov.uk/businessindustryandtrade/retailindustry/methodologies/retailsalesindexrsiqmi" PaginationFields: type: object properties: count: description: "The number of items returned." readOnly: true type: integer example: 20 limit: description: "The number of items requested." type: integer default: 20 minimum: 0 maximum: 1000 offset: description: "The offset of the first item to retrieve, starting at 0. Use this parameter as a pagination mechanism along with the limit parameter" type: integer example: 0 default: 0 total_count: description: "The total number of items available." readOnly: true type: integer example: 123