Guide to Creating your own dataset - Census 2021

Create a Custom Dataset

To create a custom dataset for Census 2021 data, there are several endpoints available to build up the query. All the endpoints below are GET requests.

Firstly, it should be determined which population the query is to be based on. The list of available populations can be accessed using:

 /population-types  

Only those populations returned which are of type microdata can be used for a create your own dataset query.

Once the population has been established, an area-type to run the query for should be selected. A list of available area-types can be found on the following URL, replacing {population-type-name} with the name of the selected population:

/population-types/{population-type-name}/area-types

It is possible to filter a custom dataset query to specific areas. To access a list of available areas for an area-type, then the following URL pattern should be used, replacing {population-type-name} with the selected population and {area-type-id} with the id of selected area-type.

/population-types/{population-type-name}/area-types/{area-type-id}/areas

If a “q” parameter is added to the /areas request, then a search is carried out on the supplied text in the parameter, e.g. /population-types/UR/area-types/ltla/areas?q=swa will return only lower tier local authorities with the text “swa” in the label.

The next step is to determine which variables are available to add to the query. These can be accessed using the following URL pattern which returns all base variables for a population:

/population-types/{population-type-name}/dimensions

If a “q” parameter is added to the /dimensions request, a search is carried out on the supplied text in the parameter, e.g. /population-types/UR/dimensions?q=age will return only variables with the text “age” in the label.

If a different level of categorisation is required for a query to be run against, these levels of categrisation can be found at the following URL pattern, replacing {population-type-name} with the name of the population and the {dimension-id} with the id returned in the /dimensions response:

/population-types/{population-type-name}/dimensions/{dimension-id}/categorisations

Once all the above have been established, the /census-observations endpoint can be used to create a custom dataset query. For example, the URL below returns information about general health and the highest level of qualification within the usual residents population at area-type level of country for England only:

/population-types/UR/census-observations?area-type=ctry,E92000001&dimensions=health_in_general,highest_qualification

The area-type is supplied in the area-type parameter, and any areas to be filtered should be added in commas after the area-type-id. Any variables should be supplied in the dimensions parameter in a comma separated list. These are the dimension-ids returned in the /dimensions and /categorisations endpoints above.