Guide to filtering a CMD dataset

The ‘Filter a dataset’ service allows any combination of dimension options to be requested. This is aimed at more complicated queries than the ‘Explore our dataset’ service and requires a POST containing dataset ID, edition, version and details of dimensions.

Any dimensions not filtered on will return all available dimension items for that dataset. If you want everything in a dataset for a specific geographic location, you only need to provide the option for that geography, for example;

{
    "dataset": {
        "id": "cpih01",
        "edition": "time-series",
        "version": 6
    },
    "dimensions": [
        {
            "name": "geography",
            "options": [
                "K02000001"
            ]
        }
    ]
}

This example body can be sent via post to create a filter, with the response giving you a unique ID. As shown in this example under filter_id:

{
    "dataset": {
        "edition": "time-series",
        "id": "cpih01",
        "version": 6
    },
    "dimensions": [
        {
            "name": "geography",
            "options": [
                "K02000001"
            ]
        }
    ],
    "events": {},
    "filter_id": "d9645c21-0baa-4a58-834e-feb1919b14bb",
    "instance_id": "bc873fb8-0797-469b-84ed-9bb3da80feeb",
    "links": {
        "dimensions": {
            "href": "https://api.beta.ons.gov.uk/v1/filters/d9645c21-0baa-4a58-834e-feb1919b14bb/dimensions"
        },
        "filter_blueprint": {},
        "filter_output": {},
        "self": {
            "href": "https://api.beta.ons.gov.uk/v1/filters/d9645c21-0baa-4a58-834e-feb1919b14bb"
        },
        "version": {
            "href": "https://api.beta.ons.gov.uk/v1/datasets/cpih01/editions/time-series/versions/6",
            "id": "6"
        }
    },
    "published": true
}

Further PUT requests can be made to /filters/{filter-ID} to update the dimensions required and once the request is complete it can be submitted by adding ?submitted=true.

For example:

/filters/d9645c21-0baa-4a58-834e-feb1919b14bb?submitted=true

Note: ?submitted=true can be added to the initial POST request and the job will start immediately.

/filters?submitted=true

Once submitted, you will get the following response:

{
    "dataset": {
        "id": "cpih01",
        "edition": "time-series",
        "version": 6
    },
    "instance_id": "2426ff0f-ca8b-45f6-8728-e851ea165b85",
    "dimensions": [
        {
            "name": "geography",
            "options": [
                "K02000001"
            ]
        }
    ],
    "events": {},
    "filter_id": "63c77ab3-b57d-40a8-8397-9830ed98f9fd",
    "published": true,
    "links": {
        "dimensions": {
            "href": "https://api.beta.ons.gov.uk/v1/filters/63c77ab3-b57d-40a8-8397-9830ed98f9fd/dimensions"
        },
        "filter_output": {
            "id": "9dd04dd7-07e9-4ce9-90bb-a4205b743027",
            "href": "https://api.beta.ons.gov.uk/v1/filter-outputs/9dd04dd7-07e9-4ce9-90bb-a4205b743027"
        },
        "filter_blueprint": {},
        "self": {
            "href": "https://api.beta.ons.gov.uk/v1/filters/63c77ab3-b57d-40a8-8397-9830ed98f9fd"
        },
        "version": {
            "id": "6",
            "href": "https://api.beta.ons.gov.uk/v1/datasets/cpih01/editions/time-series/versions/6"
        }
    }
}

This creates a ‘filter output’ which will contain the files once generated. This is available in the response and follows this format;

"filter_output": {
    "id": "9dd04dd7-07e9-4ce9-90bb-a4205b743027",
    "href": "https://api.beta.ons.gov.uk/v1/filter-outputs/9dd04dd7-07e9-4ce9-90bb-a4205b743027"
}

A GET on the filter-output will return the following;

{
"dataset": {
    "edition": "time-series",
    "id": "cpih01",
    "version": 6
},
"dimensions": [
    {
        "name": "geography",
        "options": [
            "K02000001"
        ]
    }
],
"downloads": {
    "csv": {
        "href": "https://download.beta.ons.gov.uk/downloads/filter-outputs/a5deb5e7-bb91-47bc-bb70-f9da12d54fa1.csv",
        "size": "2061369"
    },
    "xls": {
        "href": "https://download.beta.ons.gov.uk/downloads/filter-outputs/a5deb5e7-bb91-47bc-bb70-f9da12d54fa1.xlsx",
        "size": "112878"
    }
},
"events": {},
"filter_id": "a5deb5e7-bb91-47bc-bb70-f9da12d54fa1",
"instance_id": "bc873fb8-0797-469b-84ed-9bb3da80feeb",
"links": {
    "dimensions": {},
    "filter_blueprint": {
        "href": "https://api.beta.ons.gov.uk/v1/filters/5ce923e2-613e-4dcf-874c-d750d97afe79",
        "id": "5ce923e2-613e-4dcf-874c-d750d97afe79"
    },
    "filter_output": {},
    "self": {
        "href": "https://api.beta.ons.gov.uk/v1/filter-outputs/a5deb5e7-bb91-47bc-bb70-f9da12d54fa1"
    },
    "version": {
        "href": "https://api.beta.ons.gov.uk/v1/datasets/cpih01/editions/time-series/versions/6",
        "id": "6"
    }
},
"published": true,
"state": "completed"
}

Note: The split between ‘filter’ and ‘filter-outputs’ is there to allow the filter to be modified and resubmitted.