2021 Census Profile Web Data Service User Guide

Release date: February 9, 2022 Updated on: November 15, 2023

The Census Profile, 2021 Census of Population provides a statistical overview of various geographic areas based on a number of detailed variables. Data are available according to the 2021 Census of Population release schedule. For more information, refer to 2021 Census dissemination planning: Release plans. Note: The data for the topics Education, Labour, Language of work, Commuting and Instruction in the minority official language will be available at a later date.

The 2021 Census Profile Application Programming Interface (API) is compliant with the Statistical Data and Metadata eXchange (SDMX) RESTful API Specifications and you can find useful documentation and a cheat sheet (PDF, 83 KB) on the SDMX Technical Working Group’s website.This guide refers to terms and technical elements as defined in the standard.

With the SDMX API, users can request various dimensions as a parameter in the Uniform Resource Locator (URL) such as geographies and characteristics. The resulting data can be downloaded as a comma-separated value (CSV), JavaScript Object Notation (JSON) and Extensible Markup Language (XML).

The Statistical Data and Metadata eXchange standard

The SDMX is an International Organization for Standardization (ISO) standard (ISO 17369:2013) that has been designed to describe statistical data and metadata. Statistics Canada and many other statistical organizations have adopted this standard for statistical data exchange.

It is used to define a common data model and uses standardized data access interfaces, known as APIs.

Data model overview

All elements of a specific domain can be described using concepts. These concepts can be broken down into dimensions, attributes and observation values. Grouped together, they form a concept scheme.

In the SDMX, the data are managed using dataflows, which each contain a set of data with a common structure (e.g., census data values about the profile characteristics of geographies). These structural metadata are represented using a Data Structure Definition (DSD), which can be reused across dataflows. Imagine the dataflow as a container for data with a common structure (similar topics are usually grouped, with the structure based on a hypercube model). For census profiles, dataflows are unique for the different geography levels.

A set of dimensions are used to define the data structure definition and the dataflow. Census profile data are structured with the following dimensions:

To maintain a controlled list of codes, the allowed values for each dimension are kept in a codelist. This means that, for example, the codelist connected to the frequency dimension would contain the list of allowed frequencies. Codelists can be used by several structures.

Each datapoint has a unique identifier called a key, which represents the combination of values in each dimension. The order of the dimension in the dimension list is important in building the key. The key consists of the list of dimension values for each dimension separated by a dot (.) and lists the dimension by the order it appears in the DSD dimension list. For example, the key ".2021A000235..1." represents filtering the dataset by the Geography=Province of Ontario (2021A000235) and Profile Characteristic=Population, 2021 (1). In this example, the key could be easily applied to the DF_PR (Canada, provinces and territories) dataflow.

An observation can have attributes attached to it such as the unit of measure, comments, and footnotes.

SDMX can be represented using different access formats, such as:

Statistical Data and Metadata eXchange data web service

All the data stored for census profiles can be retrieved using the query string described below:

protocol://wsEntryPoint/resource/flowRef/key?parameters

Syntax definition

protocol
The web service is available over Hypertext Transfer Protocol (HTTP), http and https.
wsEntryPoint
The web service entry point is available at the same location of the SDMX data and metadata entry point, i.e., "api.statcan.gc.ca/census-recensement/profile/sdmx/rest/".
resource
The resource for queries is data.
flowRef

A reference to the dataflow describing the data that must be returned.

Syntax refers to the identifier of the agency that is maintaining the dataflow, followed by the dataflow identifier, then the dataflow version, each separated by a comma (,).

For example, in the reference "STC_CP,DF_PR,1.1", the agency is STC_CP, it maintains the DF_PR dataflow and the version of the dataflow is 1.1. The first release of the Census Profile (February 9, 2022) refers to version 1.0.

The important component above is the dataflow name (DF_PR).

If the flowRef value has only one element, it is referred to as the identifier of the dataflow. The identifier for the agency will default to "all", while the value for the dataflow version will default to "latest".

If the flowRef value has two elements, they are referred to as the identifier of the agency and the identifier of the dataflow. The version will default to "latest".

Below is the list of the supported dataflows for census profiles:

Dataflow Name of dataflow
DF_ADA aggregate dissemination areas
DF_CD census divisions
DF_CMACA census metropolitan areas and census agglomerations
DF_CSD census subdivisions (municipalities)
DF_CT census tracts
DF_DA dissemination areas
DF_DCSD dissolved census subdivisions
DF_DPL designated places
DF_ER economic regions
DF_FED (1.3) federal electoral districts (2013 Representation Order)
Example: 
https://api.statcan.gc.ca/census-recensement/profile/sdmx/rest/data/STC_CP,DF_FED,1.3/A5.2013A000410001.1..1
DF_FED (2.0) federal electoral districts (2023 Representation Order)
Example: 
https://api.statcan.gc.ca/census-recensement/profile/sdmx/rest/data/STC_CP,DF_FED,2.0/A5.2023A000410001.1..1
DF_FSA forward sortation areas©
DF_HR health regions
DF_POPCNTR population centres
DF_PR Canada, provinces and territories
key

As explained in the data model, the combination of dimensions allows statistical data to be uniquely identified. In the SDMX, this combination is known as a series key—it is needed in the key parameter.

Let's say, for example, that Census Profile values can be uniquely identified by the following:

  • frequency at which they are measured (e.g., every five years = code A5)
  • geography being referenced (e.g., province of Ontario = code 2021A000235)
  • gender (e.g., total gender = code 1)
  • Census Profile characteristic (e.g., population count for 2021 = code 1)
  • statistic (e.g., counts = code 1).

To build the series key, you must take the value for each of the dimensions (in the order in which the dimensions are defined in the DSD) and join them with a dot (.). The series key for the example above therefore becomes A5.2021A000235.1.1.1.

Wildcarding is supported by omitting the value for the dimension to be wildcarded. For example, the following series key can be used to retrieve the data for all profile characteristics for the province of Ontario: A5.2021A000235.1..1.

Use the plus (+) character as the "OR" operator. For example, the following key can be used to retrieve the data for all profile characteristics for the provinces of Ontario and Quebec: A5.2021A000235+2021A000224.1..1.

parameters

In this query string, parameters are defined as

startPeriod=value&endPeriod=value&firstNObservations=value&lastNObservations=value&detail=value&format=value

In the case of census profiles, the applicable parameters are detail and format.

detail

To specify the amount of information you want to be returned by the web service, use the detail parameter.

Possible options include:

  • full: All data, including series and observations, and attributes will be returned. This is the default.
  • dataonly: The returned message will exclude attributes.
  • serieskeysonly: The returned message will include only the series. Attributes and observations will be excluded. For example, this option would allow you to list series matching a specific query, but not return the actual data.
  • nodata: The returned message will include the series, as well as the attributes, but not the observations.
format

Using the format parameter, you can instruct the web service to return data in different formats (see also Content negotiation).

Possible options are:

  • csv
  • jsondata

Examples

Since there will be a total of seven releases, resulting in seven versions of each dataflow, we modified the examples below, removing the version detail. As a result, the version will default to "latest".

  1. Retrieve the data for the Cornwall census agglomeration (All Gender / All Statistics) for the DF_CMACA dataflow.

    https://api.statcan.gc.ca/census-recensement/profile/sdmx/rest/data/STC_CP,DF_CMACA/A5.2021S0504501...

  2. Retrieve the provincial data for the provinces of Ontario and Quebec (All Gender / All Statistics) for the DF_PR dataflow.

    https://api.statcan.gc.ca/census-recensement/profile/sdmx/rest/data/STC_CP,DF_PR/A5.2021A000235+2021A000224.1..1

Please note that it is not advisable to download all data related to a dataflow. If this is what you intend to do, please go to Census Profile, 2021 Census of Population - Download files where the complete data for each dataflow is available for download.

Statistical Data and Metadata eXchange metadata web service

All metadata can be retrieved using the query string described below.

protocol://wsEntryPoint/resource/agencyID/resourceID/version?detail=value&references=value

Syntax definition

protocol

The web service is available over https.

wsEntryPoint

The web service entry point is available at the same location of the SDMX metadata entry point, i.e., "api.statcan.gc.ca/census-recensement/profile/sdmx/rest/".

resource

The following resources are supported by the web service: datastructure, codelist and dataflow. Please note that not all of them are used at the moment.

agencyID

Organizations defining metadata are known as agencies in the SDMX. To retrieve an artefact, you should know the identifier of its maintainer. The agencyID code to represent the Census Profile for Statistics Canada is STC_CP.

resourceID

The identifier of the resource, such as CL_GEO_CMACA for the census metropolitan areas and census agglomerations codelist, are maintained by the agency, which in this case is STC_CP.

version

The version of the artefact to be returned. When the version number is not supplied, the latest version of the resource is returned.

detail

You can specify the desired amount of information to be returned by using the detail parameter. For example, it is possible to instruct the web service to return only basic information about the resource (i.e., its ID, agencyID, version and name). This is also known in the SDMX as a stub.

The allowed values are:

  • full: All available information for all artefacts will be returned. This is the default.
  • allstubs: All artefacts will be returned as stubs.
  • referencestubs: The referenced artefacts will be returned as stubs.
references

You can instruct the web service to return (or not) the artefacts referenced by the artefact to be returned (e.g., the codelists and concepts used by the DSD matching the query) by using the references parameter. You can also retrieve the artefacts that use the matching artefact (e.g., the dataflows that use the DSD matching the query).

Possible values are:

  • none: No references will be returned. This is the default.
  • parents: The artefacts that use the artefact matching the query (e.g., the dataflows that use the DSD that match the query) will be returned.
  • parentsandsiblings: The artefacts that use the artefact matching the query, as well as the artefacts referenced by these artefacts will be returned.
  • children: The artefacts referenced by the matching artefact will be returned (e.g., the concept schemes and codelists used in a DSD).
  • descendants: References of references, up to any level, will also be returned.
  • all: The combination of parentsandsiblings and descendants will be returned.

A concrete type of resource may also be used (e.g., references=codelist).

Examples

  1. Retrieve the latest version in production of the CL_GEO_CMACA codelist.

    https://api.statcan.gc.ca/census-recensement/profile/sdmx/rest/codelist/STC_CP/CL_GEO_CMACA/latest

  2. Retrieve all of the dataflows within the SDMX environment maintained by the agency (AgencyID = STC_CP).

    https://api.statcan.gc.ca/census-recensement/profile/sdmx/rest/dataflow/STC_CP/all/latest

  3. Retrieve all of the related metadata for the Canada, provinces and territories dataflow (DF_PR).

    https://api.statcan.gc.ca/census-recensement/profile/sdmx/rest/dataflow/STC_CP/DF_PR?references=all

Content negotiation

You can select the representation to be returned by using the HTTP content negotiation mechanism. You can also instruct the service to compress the data to be returned.

Format selection

The following data formats are supported by the web service:

Generic mime types (application/json, application/xml) are also supported, but they will always point to the most recent version of the SDMX formats supported by these web services. That version will change in the future whenever new versions of the various SDMX formats are made available.

It is therefore highly recommended that implementers use one of the specific mime types above rather than a generic one to avoid issues when new versions of the formats are released.

Output compression

You can also enable data compression using the Accept-Encoding HTTP header field. Compressed messages are typically much smaller than uncompressed messages, which can lead to improvements when transferring large amount data over the network.

Status codes

The web service returns the following HTTP status codes.

Code Status Description
200 OK Your query could be successfully processed and the data have been returned.
304 No changes No changes since the timestamp supplied in the If-Modified-Since header.
400 Syntax error If there is a syntactic or semantic issue with the parameters you supplied, a 400 HTTP status code will be returned.
404 No results found A 404 HTTP status code will be returned if there are no results matching the query.
406 Not Acceptable If you ask for a resource representation that we don't support, a 406 HTTP status code will be returned. See the section about content negotiation, to view the supported representations.
500 Internal Server Error When there is an issue on our side, a 500 HTTP status code will be returned. Feel free to try again later or to contact our support hotline.
501 Not implemented This web service offers a subset of the functionality offered by the SDMX RESTful web service specification. When you use a feature that we have not yet implemented, a 501 HTTP status code will be returned.
503 Service unavailable If our web service is temporarily unavailable, a 503 HTTP status code will be returned.

Useful tips

The SDMX Technical Working Group publishes a useful list of tips and tricks for web service clients worth reading.

The SDMX Technical Working Group has also published a two-page cheat sheet (PDF, 83 KB) that summarizes the main points of the SDMX 2.1 RESTful API.

If the documentation does not contain the information you require, or if you have any general comments or feedback regarding our web service, please contact us.

All sample queries in this document can also be executed using command-line tools such as curl or wget: 


wget -O data.xml \
--header="Accept:application/vnd.sdmx.structurespecificdata+xml;version=2.1" \
https://api.statcan.gc.ca/census-recensement/profile/sdmx/rest/data/STC_CP,DF_CMACA/A5.2021S0504501...
curl -k -o data.xml \
--header "Accept:application/vnd.sdmx.structurespecificdata+xml;version=2.1" \
https://api.statcan.gc.ca/census-recensement/profile/sdmx/rest/data/STC_CP,DF_CMACA/A5.2021S0504501...

Related information

Date modified: