CensusAPI

wrapper.CensusAPI(self, verify=True)

A wrapper for the 2021 England and Wales Census API.

Parameters

Name	Type	Description	Default
verify	bool	Whether to use SSL verification. Defaults to True.	True

Methods

Name	Description
get	Make a call to, and retrieve some data from, the API.
query_categories	Query metadata on the categories of a particular feature item.
query_feature	Query metadata on a feature for a population type.
query_population_types	Query the metadata for a set of population types.
query_table	Query a custom table from the API.

get

wrapper.CensusAPI.get(url)

Make a call to, and retrieve some data from, the API.

Parameters

Name	Type	Description	Default
url	str	URL from which to retrieve data.	required

Returns

Type	Description
dict or None	JSON data from the response of this API call if it is successful, and None otherwise.

query_categories

wrapper.CensusAPI.query_categories(population_type, feature, item)

Query metadata on the categories of a particular feature item.

This method connects to different endpoints depending on feature:

• /{population_type}/area-types/{item}/areas
• /{population_type}/dimensions/{item}/categorisations

Parameters

Name	Type	Description	Default
population_type	str	Population type to query.	required
feature	(area - types, dimensions)	Endpoint of the feature to query.	"area-types"
item	str	ID of the item in the feature to query.	required

Returns

Type	Description
pandas.pandas.DataFrame or None	Metadata on the categories for the feature item if the call succeeds, and None if not.

query_feature

wrapper.CensusAPI.query_feature(population_type, feature, *items)

Query metadata on a feature for a population type.

This method connects to the area-types and dimensions endpoints (ie. /{population_type}/{endpoint}) and returns a data frame format of the metadata there.

Parameters

Name	Type	Description	Default
population_type	str	Population type to query.	required
feature	(area - types, dimensions)	Endpoint of the feature to query.	"area-types"
*items	str	Items to query from the endpoint. If not specified, return all items at the endpoint. For dimensions, see census21api.constants.DIMENSIONS_BY_POPULATION_TYPE, and census21api.constants.AREA_TYPES_BY_POPULATION_TYPE for area types.	()

Returns

Type	Description
pandas.pandas.DataFrame or None	Data frame with the metadata if the call succeeds, and None if not.

query_population_types

wrapper.CensusAPI.query_population_types(*population_types)

Query the metadata for a set of population types.

This method finds all available population types and retrieves their metadata from the population-types endpoint, returning the combined information as a data frame.

Parameters

Name	Type	Description	Default
population_types	str	Population types to be queried. If not specified, metadata on all the population types are returned. See census21api.constants.POPULATION_TYPES.	()

Returns

Type	Description
pandas.pandas.DataFrame or None	Data frame with all the population type metadata. If none of the API calls are successful, returns None.

query_table

wrapper.CensusAPI.query_table(population_type, area_type, dimensions, use_id=True)

Query a custom table from the API.

This method connects to the census-observations endpoint /{population_type}/census-observations with query parameters ?area-type={area_type}&dimensions={','.join(dimensions)}.

Parameters

Name	Type	Description	Default
population_type	str	Population type to query. See census21api.constants.POPULATION_TYPES.	required
area_type	str	Area type to query. See census21api.constants.AREA_TYPES_BY_POPULATION_TYPE.	required
dimensions	list of str	Dimensions to query. See census21api.constants.DIMENSIONS_BY_POPULATION_TYPE.	required
use_id	bool	If True (the default) use the ID for each dimension and area type. Otherwise, use the full label.	True

Returns

Type	Description
pandas.pandas.DataFrame or None	Data frame containing the data from the API call if it is successful and without blocked pairs, and None otherwise.