knitr::opts_chunk$set( collapse = TRUE, comment = "#>", eval = nzchar(Sys.getenv("COMPILE_VIG")) ) library(cancensus) library(dplyr) # options(cancensus.api_key = "your_api_key")
The cancensus package was developed to provide users with a way to access Canadian Census in a programmatic way following good tidy data practices. While the structure and data in cancensus is unique to Canadian Census data, this package is inspired in part by tidycensus, a package to interface with the US Census Bureau data APIs.
As Statistics Canada does not provide direct API access to Census data, cancensus retrieves Census data indirectly through the CensusMapper API. CensusMapper is a project by Jens von Bergmann, one of the authors of cancensus, to provide interactive geographic visualizations of Canadian Census data. CensusMapper databases store all publically available data from Statistics Canada for the 2006, 2011, and 2016 Censuses. Censusmapper data can be accessed via an API and cancensus is built to interface directly with it.
cancensus requires a valid CensusMapper API key to use. You can obtain a free API key by signing up for a CensusMapper account. CensusMapper API keys are free; however, API requests are limited in volume. For larger quotas, please get in touch with Jens directly.
To check your API key, just go to "Edit Profile" (in the top-right of the CensusMapper menu bar). Once you have your key, you can store it in your system environment so it is automatically used in API calls. To do so just enter
options(cancensus.api_key = "your_api_key").
The stable version of cancensus can be easily installed from CRAN.
install.packages("cancensus") library(cancensus) options(cancensus.api_key = "your_api_key") options(cancensus.cache_path = "custom cache path")
Alternatively, the latest development version can be installed from Github using
# install.packages("devtools") devtools::install_github("mountainmath/cancensus") library(cancensus) options(cancensus.api_key = "your_api_key") options(cancensus.cache_path = "custom cache path")
For performance reasons, and to avoid unneccessarily drawing down API quotas, cancensus caches data queries under the hood. By default, cancensus caches in R's temporary directory, but this cache is not persistent across sessions. In order to speed up performance, reduce quota usage, and reduce the need for unnecessary network calls, we recommend assigning a persistent local cache using
options(cancensus.cache_path = 'XXX'), this enables better control over the data. Users will be prompted with a suggestion to change their default cache location when making API calls if one has not been set yet.
Setting the API key and the cache path in the
.Rprofile facilitates the ability to share code without exposing API keys or relying on the local directory structure.
cancensus provides three different functions for retrieving Census data:
get_census to retrieve Census data and geography as a spatial dataset
get_census_data to retrieve Census data only as a flat data frame
get_census_geometry to retrieve Census geography only as a collection of spatial polygons.
get_census takes as inputs a dataset parameter, a list of specified regions, a vector of Census variables, and a Census geography level. You can specify one of three options for spatial formats:
NA to return data only,
sf to return an sf-class data frame, or
sp to return a SpatialPolygonsDataFrame object.
# Returns a data frame with data only census_data <- get_census(dataset='CA16', regions=list(CMA="59933"), vectors=c("v_CA16_408","v_CA16_409","v_CA16_410"), level='CSD', use_cache = FALSE, geo_format = NA) # Returns data and geography as an sf-class data frame census_data <- get_census(dataset='CA16', regions=list(CMA="59933"), vectors=c("v_CA16_408","v_CA16_409","v_CA16_410"), level='CSD', use_cache = FALSE, geo_format = 'sf') # Returns a SpatialPolygonsDataFrame object with data and geography census_data <- get_census(dataset='CA16', regions=list(CMA="59933"), vectors=c("v_CA16_408","v_CA16_409","v_CA16_410"), level='CSD', use_cache = FALSE, geo_format = 'sp')
cancensus utilizes caching to increase speed, minimize API token usage, and to make data available offline. Downloaded data is hashed and stored locally so if a call is made to access the same data, cancensus will read the local version instead. To force cancensus to refresh the data, specify
use_cache = FALSE as a parameter for
Additional parameters for advanced options can be viewed by running
cancensus can access Statistics Canada Census data for the 2006 Census, the 2011 Census and National Household Survey, as well as the latest available data from the 2016 Census. Additional data for the 2016 Census will be included in Censusmapper within a day or two after public release by Statistics Canada. Statistics Canada maintains a release schedule for the Census 2016 Program which can be viewed on their website.
To view available datasets, run
As other Census datasets become available via the CensusMapper API, they will be listed as output when calling
Census data is aggregated at multiple geographic levels. Census geographies at the national (C), provincial (PR), census metropolitan area (CMA), census division (CD), and census subdivision (CSD) are defined as named census regions.
Canadian Census geography can change in between Census periods. cancensus provides a function,
list_census_regions(dataset), to display all named census regions and their corresponding id for a given census dataset.
regions parameter in
get_census requires as input a list of region id strings that correspond to that regions geoid. You can combine different regions together into region lists.
# Retrieves Vancouver and Toronto list_census_regions('CA16') %>% filter(level == "CMA", name %in% c("Vancouver","Toronto")) census_data <- get_census(dataset='CA16', regions=list(CMA=c("59933","35535")), vectors=c("v_CA16_408","v_CA16_409","v_CA16_410"), level='CSD', use_cache = FALSE)
Census data accessible through cancensus comes is available in a number of different aggregation levels including:
| Code | Description | Count in Census 2016 | | --------|-------------------------------|:--------------------:| | C | Canada (total) | 1 | | PR | Provinces/Territories | 13 | | CMA | Census Metropolitan Area | 49 | | CD | Census Division | 287 | | CSD | Census Subdivision | 713 | | CT | Census Tracts | 5621 | | DA | Dissemination Area | 56589 | | Regions | Named Census Region | |
regions = "59933" and
level = "CT" will return data for all 478 census tracts in the Vancouver Census Metropolitan Area. Selecting
level = "DA" will return data for all 3450 dissemination areas. Working with CT and DA level data significantly increases the size of data downloads and API usage. cancensus relies on local data caching to reduce usage and load times.
level = "Regions" will produce data strictly for the selected region without any tiling of data at lower census aggregation levels levels.
Census data contains thousands of different geographic regions as well as thousands of unique variables. In addition to enabling programmatic and reproducible access to Census data, cancensus has a number of tools to help users find the data they are looking for.
list_census_vectors(dataset) to view all available Census variables for a given dataset.
For each variable (vector) in that Census dataset, this shows:
Each Census dataset features numerous variables making it a bit of a challenge to find the exact variable you are looking for. To help with that, this package includes a built-in vector search tool to help find specific variables.
# Find the variable indicating the number of people of Austrian ethnic origin search_census_vectors("Austrian", dataset = 'CA16')
Knowing exactly how to spell the right variable can be tricky, but this search function relies on fuzzy searching so if it is unable to find an exact match of your search term, it will provide some helpful alternatives. In this case, searching for "Austraian" origin will show search terms for the vectors for both Austrian and Australian origins.
# Find the variable indicating the number of people of Austrian ethnic origin search_census_vectors("Austraian", dataset = 'CA16')
Census variables are frequently hierarchical. As an example, consider the variable for the number of people of Austrian ethnic background. We can select that vector and quickly look up its entire hierarchy using
parent_census_vectors on a vector list.
list_census_vectors("CA16") %>% filter(vector == "v_CA16_4092") %>% parent_census_vectors()
Sometimes we want to traverse the hierarchy in the oppposite direction. This is frequently required when looking to compare different variable stems that share the same aggregate variable. As an example, if we want to look the total count of Northern European ethnic origin respondents disaggregated by individual countries, it is pretty easy to do so.
# Find the variable indicating the Northern European aggregate search_census_vectors("Northern European", dataset = 'CA16')
The search result shows that the vector v_CA16_4092 represents the aggregate for all Northern European origins. The
child_census_vectors function can return a list of its constituent underlying variables.
# Show all child variable leaves list_census_vectors("CA16") %>% filter(vector == "v_CA16_4122") %>% child_census_vectors(leaves = TRUE)
leaves = TRUE parameter specifies whether intermediate aggregates are included or not. If
TRUE then only the lowest level variables are returns - the "leaves" of the hierarchical tree.
Any scripts or data that you put into this service are public.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.