Canadian Census Data and Geography from the 'CensusMapper' API

Integrated, convenient, and uniform access to Canadian Census data and geography retrieved using the 'CensusMapper' API. This package produces analysis-ready tidy data frames and spatial data in multiple formats, as well as convenience functions for working with Census variables, variable hierarchies, and region selection. API keys are freely available with free registration at <>. Census data and boundary geometries are reproduced and distributed on an "as is" basis with the permission of Statistics Canada (Statistics Canada 2006; 2011; 2016).

Build Status CRAN_Status_Badge CRAN_Downloads_Badge

Access, retrieve, and work with Canadian Census data and geography.

  • Download data and Census geography in tidy and analysis-ready format
  • Convenience tools for searching for and working with Census regions and variable hierarchies
  • Provides Census geography in multiple R spatial formats
  • Provides data and geography at multiple Census geographic levels including province, Census Metropolitan Area, Census Division, Census Subdividision, Census Tract, and Dissemination Areas
  • Provides up-to-date data for the 2016, 2011, and 2006 Censuses


Cancensus home page and reference guide

Installing the package


Alternatively, the latest development version can be installed from Github.


API key

This package relies on queries to the CensusMapper API, which requires a Censusmapper API key. 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").

Local Cache

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. This option can be stored stored in your .Rprofile alongside your API key. Users will be prompted with a suggestion to change their default cache location when making API calls if one has not been set yet.

Currently available datasets

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. You can run list_census_datasets to check what datasets are currently available for access through the CensusMapper API. 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.

Picking regions and variables

Census data contains thousands of different geographic regions as well as thousands of unique variables. There are several useful functions within cancensus to simplify accessing Census metadata, locating regions, and identifying variables.

# To view available Census datasets

# To view available named regions at different levels of Census hierarchy for the 2016 Census (for example)

# To view available Census variables for the 2016 Census

There is also an interactive tool that is available at CensusMapper API call generator to visually select regions and variables and generate code for the API call.

Getting the data

cancensus can return census data with or without associated Census geographical information that can be used for mapping and GIS. By default, cancensus returns tidy tabular data only, but has options to return spatial data objects in either sf or sp formats.

# Return 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')

# Return 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', geo_format = "sf")

# Return a SpatialPolygonsDataFrame
census_data <- get_census(dataset='CA16', regions=list(CMA="59933"), vectors=c("v_CA16_408","v_CA16_409","v_CA16_410"), level='CSD', geo_format = "sp")

cancensus attempts to minimize bandwidth usage and download time by caching downloads. When attempting to download data that has previously been downloaded, cancensus will instead access the locally cached equivalent.

Examples of work using cancensus

We'd love to feature examples of work or projects that use cancensus.



  • We encourage contributions to improve this project. The best way is through issues and pull requests.
  • If you want to get in touch, we are pretty good at responding via email or via twitter at @dshkol or @vb_jens.

Cite cancensus

If you wish to cite cancensus:

von Bergmann, J., Aaron Jacobs, Dmitry Shkolnik (2017). cancensus: an R package to access, retrieve, and work with Canadian Census data and geography. v0.1.6.

A BibTeX entry for LaTeX users is

    author = {Jens {von Bergmann} and Dmitry Shkolnik and Aaron Jacobs},
    title = {cancensus: An R Package to Access, Retrieve, and Work With Canadian Census Data and Geography},
    year = {2017},
    note = {R package version 0.1.6},
    url = {},

Related packages

The cancensus package is designed for working with Canadian Census data. In addition to Census data, Statistics Canada provides access to a vast socio-economic data repository with thousands of data tables available for public access.

The cansim package is designed to retrieve and work with public Statistics Canada data tables. The cansim prepares retrieved data tables as analysis-ready tidy dataframes and provides a number of convenience tools and functions to make it easier to work with Statistics Canada data.

Data downloaded through the cansim package that comes with standard geographic attributes will typically share a common geographic ID that can be matched to Census data.

Statistics Canada Attribution

Subject to the Statistics Canada Open Licence Agreement, licensed products using Statistics Canada data should employ the following acknowledgement of source:

Acknowledgment of Source

(a) You shall include and maintain the following notice on all licensed rights of the Information:

  - Source: Statistics Canada, name of product, reference date. Reproduced and distributed on an "as is" basis with the permission of Statistics Canada.
(b) Where any Information is contained within a Value-added Product, you shall include on such Value-added Product the following notice:

  - Adapted from Statistics Canada, name of product, reference date. This does not constitute an endorsement by Statistics Canada of this product.


cancensus 0.1.8

Major changes

  • Remove dependency on development versions of sf and ggplot2 packages
  • Add feature allowing for named vector retrieval

Minor Changes

  • Vignette updates
  • Calls that retrieve only geography will now return geographic hierarchy information as well
  • Small tweaks that make it easier to do 2011-2016 intra-census comparisons

Bug fixes

  • Fix labels when geo format is sf
  • Remove some unnecessary code for geographic hierarchies

cancensus 0.1.7

Major changes

  • Set default caching to tempdir()
  • Encourage users to set up local persistent caching using options(cancensus.cache_path = 'XXX')

cancensus 0.1.6

Major changes

  • First released on CRAN

Minor changes

  • Ensured that data frames were sf-class data frames if option sf was selected for spatial data.

Bug fixes

  • Fixed a bug where read.csv was incorrectly loading text data if readr::read_csv was not available

cancensus 0.1.5

Major changes

  • Added a file to track changes to the package.
  • Added pkgdown documentation
  • New vignettes - cancensus and Making maps with cancensus

Minor changes

  • Default behaviour for list_census_vectors() changed to have quiet = TRUE

cancensus 0.1.0

Major changes

  • Added vector and geography search and discovery capabilities
  • Improved performance
  • Error and API issue messaging

Minor changes

  • Reduced package dependencies

cancensus 0.0.1

Major changes

  • Initial release

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.


0.1.8 by Dmitry Shkolnik, 4 months ago,,

Report a bug at

Browse source code at

Authors: Jens von Bergmann [aut] (API creator and maintainer) , Dmitry Shkolnik [aut, cre] (Package maintainer , responsible for correspondence) , Aaron Jacobs [aut]

Documentation:   PDF Manual  

MIT + file LICENSE license

Imports digest, dplyr, httr, jsonlite, rlang

Suggests knitr, ggplot2, leaflet, rmarkdown, readr, rgdal, rgeos, scales, sf, sp, tidyr

See at CRAN