Querying feature metadata

How to retrieve metadata on area types and dimensions

Two parameters you have to set to query a table from the API are an area type and some dimensions. In census21api, we call these parameters “features”. This guide shows you how to get metadata on each of these features with census21api using the CensusAPI.query_feature() method.

Getting area types

Given a population type, we use households (HH) here, we can retrieve area type metadata like so:

from census21api import CensusAPI

api = CensusAPI()

population_type = "HH"
api.query_feature(population_type, "area-types")
id label description total_count hierarchy_order population_type
0 nat England and Wales Data for both England and Wales. 1 1400 HH
1 ctry Countries Data for either the whole of England or Wales. 2 1300 HH
2 rgn Regions Data for the nine regions in England, and Wale... 10 1200 HH
3 lep Local enterprise partnerships Local enterprise partnerships (LEPs) are volun... 37 1150 HH
4 nhser NHS England regions Each NHS region is responsible for planning lo... 8 1100 HH
5 lhb Local health boards Local health boards in Wales are responsible f... 8 1000 HH
6 icb Integrated care boards Integrated care boards in England are responsi... 43 900 HH
7 sicbl Sub integrated care board locations Sub integrated care board locations have repla... 107 800 HH
8 utla23 2023 Upper tier local authorities Upper tier local authorities provide a range o... 175 750 HH
9 utla Upper tier local authorities Upper tier local authorities provide a range o... 174 700 HH
10 ltla23 2023 Lower tier local authorities Lower tier local authorities provide a range o... 318 650 HH
11 ltla Lower tier local authorities Lower tier local authorities provide a range o... 331 600 HH
12 senc Senedd constituencies Areas used to elect a member of the Senedd (MS... 41 550 HH
13 p19wpc Post-2019 Westminster Parliamentary constituen... Areas that will be used to elect members of pa... 575 525 HH
14 sener Senedd electoral regions There are five Senedd electoral regions each m... 6 520 HH
15 wpc Westminster Parliamentary constituencies Areas used to elect a member of parliament (MP... 573 500 HH
16 wd Electoral wards and divisions Areas used to elect local authority councillor... 7638 400 HH
17 msoa Middle layer Super Output Areas Middle layer Super Output Areas (MSOAs) are ma... 7264 300 HH
18 lsoa Lower layer Super Output Areas Lower layer Super Output Areas (LSOAs) are mad... 35672 200 HH
19 oa Output Areas The lowest level of geographical area for cens... 188880 100 HH

This data frame contains lots of information about the available area types for our population type:

  • id: the code for the area type
  • label: its full name
  • description: a description of the area type
  • total_count: the number of categories in the area type
  • hierarchy_order: where the area type sits in the hierarchy of area types
  • population_type: the population type you queried

Getting dimensions

We can retrieve dimensions (features of the data) in a similar way:

api.query_feature(population_type, "dimensions")
id label description total_count quality_statement_text population_type
0 accommodation_type Accommodation type (8 categories) The type of building or structure used or avai... 8 We have made changes to housing definitions si... HH
1 accom_by_dwelling_type Accommodation by type of dwelling (9 categories) Classifies dwellings by their type of accommod... 9 HH
2 heating_type Type of central heating in household (13 categ... Central heating is a heating system used to he... 13 HH
3 hh_adults_and_children_11a Adults and children in household (11 categories) Classifies households by the age of the people... 11 We have made methodological adjustments to the... HH
4 hh_adults_disabled_4a Number of disabled adults in household (4 cate... The number of adults in a household who assess... 4 HH
5 hh_adults_employment_5a Number of adults in employment in household (5... The number of employed adults in a household.\... 5 As Census 2021 was during a unique period of r... HH
6 hh_adults_num_3a Number of adults in household (3 categories) An adult in a household is any person who is n... 3 HH
7 hh_adult_welsh_speakers Welsh-speaking people in household (5 categories) Classifies households by the ability of people... 5 HH
8 hh_away_student_4a Households with students or schoolchildren liv... This measures households where resident studen... 4 HH
9 hh_carers_6a Number of unpaid carers in household (6 catego... An unpaid carer may look after, give help or s... 6 We did not ask people aged under five years wh... HH
10 hh_dependent_children_3a Dependent children in household and their age ... Classifies the number of dependent children in... 3 HH
11 hh_deprivation Household deprivation (6 categories) The dimensions of deprivation used to classify... 6 Caution should be used in interpreting this va... HH
12 hh_deprivation_education Household deprived in the education dimension ... A household is classified as deprived in the e... 3 HH
13 hh_deprivation_employment Household deprived in the employment dimension... A household is classified as deprived in the e... 3 HH
14 hh_deprivation_health Household deprived in the health and disabilit... A household is classified as deprived in the h... 3 HH
15 hh_deprivation_housing Household deprived in the housing dimension (3... A household is classified as deprived in the h... 3 HH
16 hh_disabled_4a Number of disabled people in household (4 cate... The number of people in a household who assess... 4 HH
17 hh_families_count Number of families in household (7 categories) Number of families in household. 7 HH
18 hh_families_type_12a Household type (12 categories) Classifies households in an alternative way to... 12 HH
19 hh_family_composition_37a Household composition (37 categories) Households according to the relationships betw... 37 There are quality considerations around consis... HH
20 hh_hrp_veteran Household Reference Person previously served i... Identifies whether the Household Reference Per... 5 Take care when comparing characteristics of UK... HH
21 hh_language Household language (English and Welsh) (5 cate... Classifies households by the combination of ad... 5 HH
22 hh_lifestage_13a Lifestage of Household Reference Person(13 cat... Household lifestage classifies households acco... 13 HH
23 hh_multi_ethnic_combination_8a Combination of ethnic groups in household (8 c... Classifies households by whether household mem... 8 HH
24 hh_multi_ethnic_group Multiple ethnic groups in household (6 categor... Classifies households by whether members ident... 6 HH
25 hh_multi_language Multiple main languages in household (6 catego... Classifies households by whether members speak... 6 HH
26 hh_multi_religion Multiple religions in household (10 categories) Classifies households by whether members ident... 10 HH
27 hh_multi_religion_combination Combination of religions in household (15 cate... Classifies households by the religious affilia... 15 HH
28 hh_not_limited_4a Number of people in household with a long-term... The number of people in the household who asse... 4 HH
29 hh_no_condition_4a Number of people in household with no long-ter... The number of people in the household who asse... 4 HH
30 hh_number_limited_little_4a Number of disabled people in household whose d... The number of people in the household who have... 4 HH
31 hh_number_limited_lot_4a Number of disabled people in household whose d... The number of people in the household who have... 4 HH
32 hh_persons_per_bedroom Number of people per bedroom in household (5 c... The number of household members is divided by ... 5 HH
33 hh_persons_per_room Number of people per room in household (5 cate... The number of household members is divided by ... 5 It is inappropriate to measure change in numbe... HH
34 hh_size_9a Household size (9 categories) The number of people in the household.\n\nVisi... 9 HH
35 hh_tenure_9a Tenure of household (9 categories) Whether a household owns or rents the accommod... 9 There is evidence of people incorrectly identi... HH
36 hh_veterans_5a Number of people in household who previously s... Number of people in the household who have pre... 5 Take care when comparing characteristics of UK... HH
37 hh_welsh_speaking_adults_3a Welsh-speaking adults in household (3 categories) Number of adults (aged 16 years and over) who ... 3 HH
38 hh_welsh_speak_3_plus_8a Welsh-speakers in household (8 categories) Number of people (aged 3 years and over) who c... 8 HH
39 number_bedrooms_6a Number of Bedrooms (6 categories) The number of bedrooms in a household’s accomm... 6 HH
40 number_of_cars_6a Car or van availability (6 categories) The number of cars or vans owned or available ... 6 HH
41 occupancy_rating_bedrooms_6a Occupancy rating for bedrooms (6 categories) Whether a household's accommodation is overcro... 6 HH
42 occupancy_rating_rooms_6a Occupancy rating for rooms (6 categories) Whether a household's accommodation is overcro... 6 It is inappropriate to measure change in numbe... HH
43 voa_number_of_rooms_9a Number of rooms (Valuation Office Agency) (9 c... A room can be any room in a dwelling apart fro... 9 It is inappropriate to measure change in numbe... HH
44 workers_transport Number of people who work in household and the... This groups the number of people who work in a... 18 As Census 2021 was during a unique period of r... HH

This data frame contains much of the same information as the area type metadata. However, it replaces hierarchy_order with quality_statement_text, which contains any information users should consider when interpreting data involving that dimension.

Filtering for items in a feature

You can also specify to only see some items in a feature by passing the item codes as arguments. For instance, let’s filter down our area types to only see the Output Areas:

api.query_feature(population_type, "area-types", "msoa", "lsoa", "oa")
id label description total_count hierarchy_order population_type
0 msoa Middle layer Super Output Areas Middle layer Super Output Areas (MSOAs) are ma... 7264 300 HH
1 lsoa Lower layer Super Output Areas Lower layer Super Output Areas (LSOAs) are mad... 35672 200 HH
2 oa Output Areas The lowest level of geographical area for cens... 188880 100 HH