/datasets/{id}/editions/{edition}/versions/{version}/observations

GET

Get observations from a version of the dataset. By providing a single option for each dimension, a single observation will be returned. A wildcard (*) can be provided for one dimension, to retrieve a list of observations.

Parameters

Name Type Description
edition path An edition of a dataset
id path Id that represents a dataset
version path A version of a dataset
<dimension_options> query The name of the dimension option and a single value; each option (dimension) and corresponding value (code) must exist against the version - e.g. `age=30` or one of the dimension options can be represented by a wildcard value `*` e.g. `geography=*`

Responses

200: Json object containing all metadata for a version

Example value
{
  "description": "An object containing information on a list of observations for a given version of a dataset",
  "type": "object",
  "properties": {
    "dimensions": {
      "description": "A list of dimensions for the given query",
      "type": "object",
      "properties": {
        "\u003cdimension name\u003e": {
          "description": "Each field is a dimension (\u003cdimension name\u003e) and will represent a query parameter in the request unless the query parameter is equal to a wildcard value (*)",
          "type": "object",
          "properties": {
            "option": {
              "description": "A list of links to the corresponding dimension codes for the given `dimension_options`",
              "type": "object",
              "properties": {
                "href": {
                  "description": "A link to the corresponding dimension code for the given `dimension_option`",
                  "type": "string",
                  "example": "http://localhost:8080/codelists/AB12CD34/codes/K02000001"
                },
                "id": {
                  "description": "The id of the corresponding dimension code for the given `dimension_option`",
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "limit": {
      "description": "The maximum number of observations requested when filtering on query parameters (limited to 10000). Defaults to 10000 observations.",
      "type": "integer"
    },
    "links": {
      "description": "A list of links related to this resource",
      "type": "object",
      "properties": {
        "dataset_metadata": {
          "description": "The version metadata that is associated with this resource",
          "type": "object",
          "properties": {
            "href": {
              "description": "A URL for the version metadata this resource relates to",
              "type": "string"
            }
          }
        },
        "self": {
          "description": "A link to this resource",
          "type": "object",
          "properties": {
            "href": {
              "description": "A URL to this resource",
              "type": "string"
            }
          },
          "readOnly": true
        },
        "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"
            }
          }
        }
      },
      "readOnly": true
    },
    "observations": {
      "description": "A list of observations found when filtering on query parameters",
      "type": "array",
      "items": {
        "required": [
          "observation"
        ],
        "properties": {
          "dimensions": {
            "description": "Contains a list of dimension objects associated with an observation. Each dimension combined with the top level list of dimensions result in this single observation only",
            "type": "object",
            "properties": {
              "\u003cdimension name\u003e": {
                "description": "Each field is a dimension (\u003cdimension name\u003e) and will represent a query parameter in the request as long as the query parameter is equal to a wildcard value (*)",
                "type": "object",
                "properties": {
                  "href": {
                    "description": "A link to the corresponding dimension code for the given `dimension_option`",
                    "type": "string",
                    "example": "http://localhost:8080/codelists/AB12CD34/codes/K02000001"
                  },
                  "id": {
                    "description": "The id of the corresponding dimension code for the given `dimension_option`",
                    "type": "string"
                  },
                  "label": {
                    "description": "The label corresponding to the dimension code for the given `dimension_option`",
                    "type": "string"
                  }
                }
              }
            }
          },
          "metadata": {
            "description": "Metadata related to the observation found against version of a dataset",
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "\u003ckey\u003e": {
                  "description": "A single metadata key-value pair related to the observation found against version of a dataset, for example 'coefficients of variation' or 'data marking'",
                  "type": "string"
                }
              }
            }
          },
          "observation": {
            "description": "The observation value for the selection of query parameters (dimensions) chosen",
            "type": "string"
          }
        }
      }
    },
    "offset": {
      "description": "The offset into the entire list of observations found",
      "type": "integer"
    },
    "total_observations": {
      "description": "The number of observations found",
      "type": "integer"
    },
    "unit_of_measure": {
      "description": "The unit of measure for the dataset observations",
      "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"
          }
        }
      }
    }
  }
}

400: Invalid request, reasons can be one of the following: * query parameters missing expected dimensions * query parameters contain incorrect dimensions * too many query parameters are set to wildcard (*) value; only one query parameter can be equal to *

Example value
null

404: Resource not found, reasons can be one of the following: * dataset id was incorrect * edition was incorrect * version was incorrect * observations not found for selected query paramaters

Example value
null

500: Failed to process the request due to an internal error

Example value
null