Comment MapleStats travaille avec Statistique Canada

Plusieurs services, une seule entrée

Les données de Statistique Canada passent par plusieurs services. Le Service de données Web (WDS) sert les tableaux et les séries chronologiques en JSON. Une API REST SDMX sert les mêmes tableaux en SDMX-ML. Le service de données de référence (RDaaS) contient les classifications comme le SCIAN. Le Profil du recensement de 2021 a sa propre API SDMX sur un autre hôte, celui de 2016 une API JSON distincte, et les profils de 2001 à 2016 n'existent qu'en téléchargement en bloc. Les fichiers de microdonnées à grande diffusion (FMGD) sont des archives ZIP. Des services plus petits couvrent Le Quotidien et son calendrier des diffusions, le catalogue Données, le répertoire des enquêtes, la géographie, le commerce de marchandises par produit, les bases de données ouvertes et les fichiers quotidiens de mise à jour en bloc.

Chaque service a ses identifiants, ses façons d'échouer et son propre format de corps de requête. Un agent ne devrait pas avoir à apprendre tout cela avant de répondre à une question sur les prix. MapleStats regroupe ces services en 84 outils, et l'agent ne les voit pas sous forme de liste. Le serveur présente trois outils au client : plan_query, search_tools et call_tool. L'agent trouve chaque outil de Statistique Canada par une requête en langage courant à search_tools et l'exécute par call_tool. La première requête d'une question sur Statistique Canada n'est donc pas une requête à Statistique Canada :

{
  "query": "chercher un tableau Statistique Canada"
}

[
  "wds_search_cubes",
  "nwt_stats_search_files",
  "wds_get_data_from_cube_coord",
  "wds_get_full_table_download",
  "wds_get_cube_metadata"
]

Le classement vient de l'index BM25 du serveur, construit sur le nom et la chaîne de documentation de chaque outil ; c'est le même index que la recherche de ce site. wds_search_cubes figure parmi les résultats, et c'est par lui que commence la recherche d'un tableau.

D'une question à un tableau

Chaque tableau de Statistique Canada a un identifiant de produit, le PID. C'est le numéro du tableau sans ses traits d'union : le tableau 18-10-0004-01 a le PID 18100004, puisque les deux derniers chiffres, qui désignent une vue du tableau, sont facultatifs. La ressource docs://statcan/addressing du serveur détaille les dix chiffres : deux pour le sujet, deux pour le type de produit, quatre pour le numéro séquentiel et deux pour la vue.

wds_search_cubes transforme des mots en PID par une méthode simple. Il télécharge getAllCubesListLite, la liste de tous les tableaux du WDS, la garde en cache une heure et cherche la requête comme sous-chaîne de chaque titre, français et anglais. C'est ainsi qu'il trouve le tableau de l'indice des prix à la consommation.

La correspondance de sous-chaîne a une limite claire. « consumer price index » trouve les tableaux de l'IPC parce que leur titre contient ces mots. Une question formulée autrement que les titres de Statistique Canada peut les manquer, et l'agent doit alors chercher de nouveau avec les termes de Statistique Canada. La provenance indique l'étendue de la recherche. Chaque résultat porte cansim_id, le numéro du tableau dans l'ancien système CANSIM, et release_time, la dernière diffusion du tableau.

Coordonnées et vecteurs

Un tableau de Statistique Canada est un cube. Chaque dimension a un arbre de membres, et un membre de chaque dimension désigne une série. wds_get_cube_metadata renvoie les dimensions. Le tableau de l'IPC en a deux : Géographie, avec 30 membres, et Produits et groupes de produits, avec 359.

Les identifiants de membres se répètent d'une dimension à l'autre : dans les deux, le membre 2 est la racine de l'arbre, celui qui n'a pas de parent (Canada, et Ensemble). Toutes les combinaisons n'existent pas. 30 géographies fois 359 produits donneraient 10 770 séries, mais le tableau en compte 2 139. Une coordonnée doit donc désigner une série que Statistique Canada publie.

Une coordonnée aligne un identifiant de membre par dimension, dans l'ordre des dimensions, séparés par des points. Le WDS exige toujours exactement dix positions, avec des zéros pour les dimensions que le tableau n'a pas. Le client ajoute ces zéros : demander 2.2 envoie 2.2.0.0.0.0.0.0.0.0. La réponse est le vecteur, un identifiant stable pour une série, le numéro « V » hérité de CANSIM.

Avec le vecteur, les données ne demandent plus qu'un appel. Voici la requête pour les 84 derniers mois de v41690973.

{
  "name": "wds_get_data_from_vectors",
  "arguments": {"vector_ids": [41690973], "latest_n": 84}
}

[
  {
    "product_id": 18100004,
    "coordinate": "2.2.0.0.0.0.0.0.0.0",
    "vector_id": 41690973,
    "observations": [
      // 83 mois précédents
      {
        "ref_period": "2026-08-01",
        "value": 169.8,
        "decimals": 1,
        "scalar_factor_code": 0,
        "symbol_code": 0,
        "status_code": 0,
        "security_level_code": 0,
        "release_time": "2026-09-14T08:30:00Z"
      }
    ],
    "provenance": {
      "url": "https://www150.statcan.gc.ca/t1/wds/rest/getDataFromVectorsAndLatestNPeriods"
      // + 9 autres champs
    }
  }
]

Chaque observation vient avec les codes nécessaires pour la lire :

scalar_factor_code

La puissance de dix dans laquelle la valeur est exprimée : 0 pour les unités, 3 pour les milliers, 6 pour les millions. Pour l'IPC, c'est 0.

decimals

Le nombre de décimales que Statistique Canada publie. La valeur est déjà arrondie par Statistique Canada.

symbol_code, status_code

Les symboles et les indicateurs d'état que Statistique Canada associe à une valeur, sous forme de codes. wds_get_code_sets les décode, tout comme les facteurs scalaires, les fréquences et les unités de mesure.

release_time

L'horodatage de diffusion que le WDS donne au point de données. Ce n'est pas toujours la première publication : août 2026 porte le 14 septembre 2026, mais septembre 2019, le mois le plus ancien de cet enregistrement, porte le 15 septembre 2021.

Une règle compte plus que les autres pour moi : le serveur n'applique jamais le facteur scalaire. value est exactement ce que le WDS a envoyé. Le code le dit deux fois, dans la chaîne de documentation du schéma (« deliberately NOT applied ... WDS never auto-applies it either ») et en tête de liste dans docs://statcan/gotchas. Une valeur en milliers reste en milliers, avec son code à côté. La mise à l'échelle tient en une ligne : apply_scalar_factor(value, code) multiplie par dix à la puissance du code. Je laisse cette ligne à qui utilise le chiffre, là où elle reste visible. L'outil renvoie ce que le WDS renvoie, chiffre pour chiffre.

Découper un tableau avec SDMX

Le WDS raisonne en séries : donnez-lui des vecteurs ou des coordonnées, il renvoie leurs observations. Certaines questions portent sur toute une tranche d'un grand tableau, comme chaque géographie détaillée ou chaque profession. Procéder série par série oblige alors à trouver d'abord chaque coordonnée, et télécharger le tableau complet revient à prendre bien plus de données que la question n'en demande. L'API SDMX de Statistique Canada fait le découpage côté serveur. Une clé nomme les membres voulus, dimension par dimension, et une position vide sert de joker.

La clé est la coordonnée sans ses zéros de remplissage : une position par dimension autre que le temps. sdmx_get_vector_data construit la clé à partir d'un vecteur. Il cherche la coordonnée du vecteur par le WDS, lit la structure SDMX du tableau pour compter ses dimensions et coupe la coordonnée à cette longueur. v41690973 devient la clé 2.2.

Le client tient compte de trois particularités de cette API.

Elle répond en XML

Le point d'accès SDMX de Statistique Canada renvoie du SDMX-ML, pour les données comme pour la structure, même quand la requête demande du JSON avec format=jsondata ou un en-tête Accept. Le fichier de constantes note que c'est confirmé en direct, à l'encontre d'une documentation de référence qui supposait du SDMX-JSON. Le client lit donc le XML lui-même, avec defusedxml plutôt que l'analyseur de la bibliothèque standard.

Les jokers échantillonnent les grandes dimensions

Si une dimension de plus d'une trentaine de codes reste vide, la réponse contient un échantillon clairsemé et imprévisible de ses codes, pas leur totalité. sdmx_get_key_for_dimension construit plutôt la version complète. Il lit la liste de codes de la dimension dans la structure, garde les codes terminaux (ceux qui ne sont parents d'aucun autre) et les joint par des + en une clé OR explicite, à insérer dans la clé à cette position.

Une combinaison est refusée

lastNObservations combiné à startPeriod ou à endPeriod reçoit HTTP 406. Le client refuse cette combinaison avant d'envoyer quoi que ce soit. Si un 406 revient malgré tout, l'erreur nomme la cause habituelle au lieu de transmettre le statut nu.

Microdonnées, poids et répliques

Les tableaux sont des agrégats. Un fichier de microdonnées à grande diffusion contient les enregistrements eux-mêmes, une ligne par répondant, avec des poids qui ramènent l'échantillon à l'échelle de la population. Statistique Canada distribue les FMGD dans des ZIP, et les dictionnaires qu'ils contiennent prennent plusieurs formes : dictionnaires CSV, fichiers Stata .dct et .do, fichiers d'étiquettes SPSS et fichiers SAS.

Les API de tableaux ne couvrent pas les FMGD. Le seul endroit où les trouver est le catalogue Données de Statistique Canada, que statcan_reference_search_data interroge. Une fois le fichier trouvé, statcan_pumf_get_codebook lit son dictionnaire à l'intérieur du ZIP par des requêtes HTTP partielles : on connaît les variables et les poids avant de télécharger le fichier de données. statcan_pumf_tabulate fait ensuite les calculs sur le serveur, avec DuckDB. Son premier appel télécharge le fichier dans un cache local, et les appels suivants le réutilisent.

Voici l'appel derrière le graphique du baccalauréat des démos : le fichier des particuliers du recensement de 2021, les adultes de 25 à 64 ans (groupes d'âge 9 à 16), et la part de chaque plus haut diplôme dans chaque province, sans les codes « non disponible » et « sans objet ».

{
  "name": "statcan_pumf_tabulate",
  "arguments": {
    "url": "https://www150.statcan.gc.ca/n1/pub/98m0001x/2023001/cen21_ind_98m0001x_part_rec21.zip",
    "rows": [
      "PR",
      "HDGREE"
    ],
    "statistic": "share",
    "filters": {
      "AGEGRP": ["9", "10", "11", "12", "13", "14", "15", "16"],
      "HDGREE": ["1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13"]
    }
  }
}

{
  "data_file": "data_donnees_2021_ind_v2.csv",
  "statistic": "share",
  "weight": "WEIGHT",
  "unweighted_n": 525504,
  "weighted_total": 19463104.06541252,
  "cells": [
    {
      "groups": [
        {"variable": "PR", "code": "10", "label": "newfoundland and labrador"},
        {"variable": "HDGREE", "code": "9", "label": "bachelor's degree"}
      ],
      "estimate": 13.305555555555555,
      "standard_error": 0.42801216439502804,
      "cv": 0.032167928848060565,
      "unweighted_n": 958,
      "low_count": false
    }
    // 142 autres cellules
  ]
  // + url, value_variable, filters, truncated, variance_method, notes, provenance
}

Deux éléments déterminent la justesse d'un tel tableau. Le premier est le poids. Par défaut, l'outil prend le poids principal du dictionnaire, ici WEIGHT. Il vérifie les étiquettes et la largeur des champs en plus des noms, car les noms peuvent tromper : dans la CSWC, WTQ_05 est une question sur le travail de nuit, et dans l'ESCC, DOHWT est un indicateur d'inclusion pour la taille et le poids. Les vrais poids sont des champs numériques larges : une largeur connue de moins de quatre colonnes écarte donc une variable. Le second est l'échantillon derrière chaque cellule. Chaque cellule indique son effectif non pondéré, et par défaut l'outil marque low_count celles de moins de 30 répondants.

Pour les erreurs-types, le fichier du recensement contient 16 poids de réplication, de WT1 à WT16. L'outil calcule l'estimation une fois avec le poids principal et une fois avec chaque réplique. Il additionne ensuite les écarts au carré des 16 estimations répliquées à leur moyenne, divise par 35 et prend la racine carrée. Le diviseur 35 vient du guide de l'utilisateur : c'est un ajustement de Fay sur 16 groupes, et le commentaire qui le précède dans tabulate.py en montre le calcul, (240/35) × (1/240). Statistique Canada signale que cette méthode surestime l'erreur des petites estimations.

Je reprends chaque méthode du guide de l'utilisateur de l'enquête, en citant la section. Un fichier n'en reçoit une qu'une fois son guide lu, « never by analogy with another survey », selon le commentaire qui précède la liste. 3 fichiers en ont une pour l'instant :

Pour tout autre FMGD, le résultat ne donne pas d'erreur-type, explique pourquoi et nomme les poids de réplication ou le fichier bootstrap trouvés. Les poids bootstrap des FMGD sont perturbés pour protéger la confidentialité : leurs erreurs-types sont comparables à celles de Statistique Canada, sans être identiques. Deux démos utilisent ainsi le fichier du recensement de 2021 : le baccalauréat par province et le faible revenu d'une génération d'immigration à l'autre.

Pièges découverts en direct

J'ai trouvé la plupart de ces pièges en appelant les services en direct, pas en lisant la documentation. À côté de chaque correctif, le code consigne comment j'ai confirmé le problème, pour qu'une modification ultérieure ne le défasse pas sans qu'on s'en aperçoive.

D'un appel à un script

La réponse d'un agent ne vaut que la vérification qu'on peut en faire sans lui. reproduce_code prend le nom d'un outil et ses arguments, et écrit un script R, Python, Stata ou Julia (ou une requête Power Query pour Excel) qui récupère les mêmes données directement chez Statistique Canada. Ce que fait le script dépend de l'appel :

Pour l'appel de l'IPC ci-dessus, le script R obtient les données en un seul appel à cansim, et le script Python reprend la requête WDS, http2=True compris. Les deux respectent la règle du facteur scalaire : ils gardent value tel que le WDS l'a envoyé et placent la valeur mise à l'échelle dans une colonne à part, val_norm de cansim en R et value_normalized en Python. Extraits des scripts enregistrés :

with httpx.Client(
    http2=True,
    follow_redirects=True,
    timeout=300,
    headers={"User-Agent": "Mozilla/5.0 (compatible; research script)"},
) as client:
    response = client.post('https://www150.statcan.gc.ca/t1/wds/rest/getDataFromVectorsAndLatestNPeriods', json=[{'vectorId': 41690973, 'latestN': 84}])
response.raise_for_status()
raw_path.write_bytes(response.content)

# …

# scalarFactorCode is the value's power of ten; refPer is the reference date.

data = data.with_columns(
    (pl.col("value") * 10 ** pl.col("scalarFactorCode")).alias("value_normalized"),
    pl.col("refPer").str.to_date(strict=False).alias("ref_date"),
)

data <- get_cansim_vector(c("v41690973"))

# …

# cansim adds val_norm (the value times its scalar factor) and a Date column.

data <- data |>
  filter(!is.na(val_norm))

Les autres services

Classifications. Le RDaaS contient le SCIAN, la Classification géographique type et les autres : structure, arbres de catégories, termes de l'index, exclusions et concordances qui font passer les codes d'une version à la suivante. Il a une lacune. Interrogé sur l'arbre des catégories du SCIAN actuel, 2022.1.0, il répond par un corps vide, alors que toutes les versions antérieures essayées renvoient l'arbre complet. L'outil le signale et renvoie à la concordance de 2017 à 2022, dont les codes cibles sont ceux du SCIAN actuel. Les termes de l'index ne passent au français que par un en-tête Accept-Language, que le client envoie.

Le recensement. Le Profil du recensement de 2021 est une API SDMX sur son propre hôte. Une requête choisit une géographie, de la province à l'aire de diffusion, et l'une de 2 631 caractéristiques, puis obtient les valeurs. Cette API choisit elle aussi sa langue par un en-tête Accept-Language plutôt que par un paramètre. Le profil de 2016 a une API JSON distincte, et les profils de 2001 à 2016 sont des téléchargements en bloc CSV ou TAB, dont les outils d'archives donnent les liens directs. La géographie du recensement vient d'un service ArcGIS REST qui fournit les limites et les DGUID. Il répond à toute erreur par HTTP 200 avec un objet d'erreur.

Diffusions. Le Quotidien vient de ses flux Atom, les 100 derniers jours par sujet, et du fichier JSON derrière le calendrier des diffusions, qui remonte au 14 mars 2012. wds_get_changed_cube_list liste les tableaux modifiés à une date donnée, et statcan_delta_get_file_link trouve le ZIP de mise à jour d'un jour ouvrable ; statcan_delta_read_table lit dans ce ZIP les nouveaux points de données d'un tableau sans le télécharger en entier. statcan_daily_get_release_calendar donne les dates des prochaines diffusions des indicateurs clés.

Commerce et autres espaces SDMX. cimt_get_trade lit la base de données derrière l'application du commerce de marchandises de Statistique Canada : exportations et importations mensuelles par produit du SH, pays partenaire, État américain et province, un niveau de détail que le WDS n'offre pas. sdmx_space_get_data donne accès à deux autres espaces SDMX, l'un pour le Centre canadien d'information sur l'énergie, l'autre pour des indicateurs que Statistique Canada partage avec d'autres ministères.

La liste complète des familles, avec le préfixe et le nombre d'outils de chacune, comptés dans le registre au moment de générer cette page :

Pour aller plus loin

• Les 84 outils de Statistique CanadaLes paramètres, les mots-clés et un exemple d'appel pour chaque outil.
• Les démosLes appels du recensement de cette page en graphiques, avec les appels derrière chacun.
• Connecter MapleStats à votre agentUne adresse, sans compte ni clé d'API.