README

statcanR helps you find and download data tables published by Statistics Canada. It connects to the official Web Data Service (WDS), works in English or French, and returns ordinary data frames that can be analysed with base R or your preferred R packages.

If you want to…	Use…	What you get
Describe the data you need in ordinary language	`statcan_find()`	Ranked table choices, identifiers, and an explanation of each match
Search for exact words in table titles	`statcan_search()`	An interactive table of matching titles and identifiers
Load a complete table into R	`statcan_data()`	A data frame
Load a table and also save a CSV copy	`statcan_download_data()`	A data frame and a UTF-8 CSV file

statcanR downloads the complete Statistics Canada table. Some tables are large, so check that the table is appropriate for your needs before downloading it.

Installation and upgrades

install.packages("statcanR")

install.packages("remotes")
remotes::install_github("warint/statcanR")

If you upgrade while statcanR is already loaded, restart your R session before loading it again. You can confirm the installed version with:

packageVersion("statcanR")

Version 0.3.0 keeps the established calls to statcan_search(), statcan_data(), and statcan_download_data(), so scripts written for earlier releases continue to work. The new statcan_find() function adds a more conversational way to discover a table without changing those functions.

A first workflow

library(statcanR)

1. Find a table

Describe the subject, place, and period you need when you do not yet know the table identifier:

matches <- statcan_find(
  "R&D expenditures in Quebec since 2020",
  lang = "eng",
  n = 5
)

matches[, c("title", "id", "score", "match_reason")]

It returns an ordinary data frame, ranked from the strongest match to the weakest. The id column contains the identifier needed by the download functions. The match_reason column explains why each table was included, so read the titles before selecting one. Several tables can answer different interpretations of the same request.

The geography and date are used to check the table as a whole. They do not filter the observations that will later be downloaded. After downloading, select Quebec and the years from 2020 onward using the relevant columns in that particular table.

If you already know the exact words used in a Statistics Canada title, use statcan_search() instead:

statcan_search(
  c("federal", "expenditures", "objectives"),
  lang = "eng"
)

Searches are case-insensitive. When you supply several keywords, every keyword must appear in the title. If a search is too narrow, try fewer or more general words. To search French titles, use lang = "fra".

2. Download the table into R

Copy an identifier from the search result and pass it to statcan_data(). The example below uses a small table so it is convenient to try:

table_data <- statcan_data("10-10-0001-01", lang = "eng")

The result is a data frame. Inspect its size, column names, and first rows before beginning an analysis:

dim(table_data)
names(table_data)
head(table_data)

REF_DATE contains the reference period and is converted to a Date when the source format can be interpreted safely. Coordinate columns remain character values, and INDICATOR contains the official table title.

3. Understand table identifiers and languages

Statistics Canada displays identifiers such as 10-10-0001-01. The corresponding eight-digit Product ID (PID) is 10100001. statcanR accepts either form, so these calls request the same table:

table_data <- statcan_data("10-10-0001-01", "eng")
table_data <- statcan_data("10100001", "eng")

table_fr <- statcan_data("10-10-0001-01", "fra")

Column labels supplied by Statistics Canada may differ between the English and French tables.

Save a CSV file

Use statcan_data() when you only need the data in R. Use statcan_download_data() when you also want a CSV copy. Earlier two-argument calls remain valid and save into the current working directory:

table_data <- statcan_download_data("10-10-0001-01", "eng")
getwd()

For clearer file management, create an output directory and provide it with path:

output_dir <- file.path(tempdir(), "statcanR-data")
dir.create(output_dir, showWarnings = FALSE)

table_data <- statcan_download_data(
  "10-10-0001-01",
  "eng",
  path = output_dir
)

attr(table_data, "statcan_file")

The function still returns the data frame. The statcan_file attribute records the exact path of the saved CSV file.

Catalogue and metadata caching

The table catalogue is cached for 24 hours so repeated searches are fast. statcan_find() also caches the candidate metadata used to verify a geography for seven days. Use refresh = TRUE only when you need the newest catalogue and metadata:

statcan_find(
  "population in Alberta since 2021",
  lang = "eng",
  refresh = TRUE
)

Downloading and refreshing require an internet connection. If Statistics Canada’s service is temporarily unavailable, searches can use an existing valid cache. A natural-language search can still return candidates when geography metadata is unavailable; in that case, geography_match is NA and the explanation says that the geography could not be verified. Confirm the table title, identifier, language, and output directory before retrying.

vignette("getting-started", package = "statcanR")

Licence and citation

Statistics Canada data are provided under the Statistics Canada Open Licence. The statcanR package is released under the MIT licence.

citation("statcanR")

Acknowledgements

The author thanks the Center for Interuniversity Research and Analysis of Organizations (CIRANO) for its support, along with Thibault Senegas, Jeremy Schneider, Marine Leroi, Martin Paquette, and contributors to earlier versions of the package. Errors and omissions remain the author’s.