National-Level Census Data Analysis

This example demonstrates how to retrieve and analyze national-level census data using the newly added level=’C’ functionality. This is particularly useful for establishing national baselines when comparing regional data.

Setting up pycancensus

First, import the necessary libraries and configure the API key.

import pycancensus as pc
import pandas as pd
import os

# Set your API key
api_key = os.environ.get('CANCENSUS_API_KEY')
if api_key:
    pc.set_api_key(api_key)
    print("API key configured")
else:
    print("No API key - examples will show code structure")
    print("Get your API key at: https://censusmapper.ca/users/sign_up")

Retrieving National-Level Data

The level=’C’ parameter allows you to retrieve Canada-wide census data, which is useful for establishing national baselines.

print("\nRetrieving national-level census data:")
try:
    # Get national data for 2021 Census
    national_data = pc.get_census(
        dataset='CA21',
        level='C',
        regions={'C': '01'},  # Canada
        vectors=[
            'v_CA21_1',   # Total population
            'v_CA21_2',   # Male population
            'v_CA21_3',   # Female population
        ],
        labels='short',
        use_cache=False
    )

    print(f"\nNational Census Data (CA21):")
    print(national_data)

    # Display key statistics
    total_pop = national_data['v_CA21_1'].iloc[0]
    male_pop = national_data['v_CA21_2'].iloc[0]
    female_pop = national_data['v_CA21_3'].iloc[0]

    print(f"\nNational Statistics:")
    print(f"Total Population: {total_pop:,}")
    print(f"Male: {male_pop:,} ({male_pop/total_pop*100:.1f}%)")
    print(f"Female: {female_pop:,} ({female_pop/total_pop*100:.1f}%)")

except Exception as e:
    print(f"Error retrieving national data: {e}")

Comparing Regional vs National Data

A common analysis pattern is to compare regional demographics against national baselines. This example compares Toronto’s demographics with national averages.

print("\nComparing regional vs national demographics:")
try:
    # Get national income data
    national_income = pc.get_census(
        dataset='CA21',
        level='C',
        regions={'C': '01'},
        vectors=[
            'v_CA21_923',  # Total household income groups
            'v_CA21_939',  # $100,000 and over
        ],
        labels='short',
        use_cache=False
    )

    # Get Toronto CMA income data
    toronto_income = pc.get_census(
        dataset='CA21',
        level='CMA',
        regions={'CMA': '535'},  # Toronto CMA
        vectors=[
            'v_CA21_923',  # Total household income groups
            'v_CA21_939',  # $100,000 and over
        ],
        labels='short',
        use_cache=False
    )

    # Calculate proportions
    nat_total = national_income['v_CA21_923'].iloc[0]
    nat_high_income = national_income['v_CA21_939'].iloc[0]
    nat_prop = nat_high_income / nat_total * 100

    tor_total = toronto_income['v_CA21_923'].iloc[0]
    tor_high_income = toronto_income['v_CA21_939'].iloc[0]
    tor_prop = tor_high_income / tor_total * 100

    print(f"\nHousehold Income Comparison ($100k+):")
    print(f"National: {nat_high_income:,} / {nat_total:,} = {nat_prop:.1f}%")
    print(f"Toronto:  {tor_high_income:,} / {tor_total:,} = {tor_prop:.1f}%")
    print(f"Difference: {tor_prop - nat_prop:+.1f} percentage points")

    if tor_prop > nat_prop:
        print(f"\nToronto has a higher proportion of high-income households")
    else:
        print(f"\nToronto has a lower proportion of high-income households")

except Exception as e:
    print(f"Error in comparison analysis: {e}")

Multi-Year National Comparison

National-level data is also useful for analyzing trends over time across different Census years.

print("\nComparing national data across Census years:")
try:
    # Get 2021 data
    national_2021 = pc.get_census(
        dataset='CA21',
        level='C',
        regions={'C': '01'},
        vectors=['v_CA21_1'],  # Total population
        labels='short',
        use_cache=False
    )

    # Get 2016 data
    national_2016 = pc.get_census(
        dataset='CA16',
        level='C',
        regions={'C': '01'},
        vectors=['v_CA16_1'],  # Total population
        labels='short',
        use_cache=False
    )

    pop_2021 = national_2021['v_CA21_1'].iloc[0]
    pop_2016 = national_2016['v_CA16_1'].iloc[0]
    growth = pop_2021 - pop_2016
    growth_pct = (pop_2021 / pop_2016 - 1) * 100

    print(f"\nNational Population Growth (2016-2021):")
    print(f"2016: {pop_2016:,}")
    print(f"2021: {pop_2021:,}")
    print(f"Growth: {growth:,} ({growth_pct:.2f}%)")

except Exception as e:
    print(f"Error in multi-year comparison: {e}")

Summary

This example demonstrated:

1. Retrieving national-level data using level=’C’

2. Comparing regional demographics against national baselines

3. Analyzing national trends across Census years

National-level data is essential for contextualizing regional analyses and understanding how local areas compare to the country as a whole.