Guide de l'utilisateur du service de données Web du Centre canadien d'information sur l'énergie

Le Centre canadien d'information sur l'énergie (CCIE) est un guichet unique pratique permettant d'obtenir des renseignements indépendants et fiables sur l'énergie au Canada. Il comprend des ressources sur tout ce qui a trait à l'énergie, y compris la production, la consommation et le commerce international.

Le CCIE offre un service de données Web pour extraire des données et des métadonnées à partir des ensembles de données accessibles sur le site Web du CCIE. Les ensembles de données disponibles seront ajoutés au service de données Web de façon régulière.

L'interface de programmation d'application (IPA) du CCIE est conforme aux spécifications de l'IPA RESTful pour l'initiative « Statistical Data and Metadata eXchange (SDMX) ». Vous trouverez de la documentation et un aide-mémoire sur le site Web du groupe de travail technique SDMX (anglais seulement)S'ouvre dans un nouveau onglet. Le présent guide fait mention de termes et d'éléments techniques tels qu'ils sont définis dans la norme SDMX.

À l'aide de l'IPA SDMX, les utilisateurs peuvent demander d'avoir diverses dimensions comme paramètre dans le localisateur de ressources uniforme (adresse URL) telles que les flux physiques, les secteurs et les produits. Les données qui en résultent peuvent être téléchargées sous forme de valeurs séparées par des virgules (CSV), de notation objet issue de JavaScript (JSON) et de langage de balisage extensible (XML).

La norme de l'échange de données et de métadonnées statistiques

La norme SDMX (anglais seulement)S'ouvre dans un nouveau onglet est une norme de l'Organisation internationale de normalisation (ISO) (ISO 17369:2013) qui a été conçue pour décrire des données et des métadonnées statistiques. Statistique Canada et bon nombre d'autres organismes de statistique ont adopté cette norme pour permettre l'échange de données statistiques.

Elle est utilisée pour déterminer un modèle de données commun et elle repose sur l'utilisation d'interfaces normalisées d'accès aux données, connues sous le nom d'IPA.

Aperçu du modèle de données

Tous les éléments d'un domaine particulier peuvent être décrits au moyen de concepts. Ces concepts peuvent être répartis par dimensions, attributs et valeurs d'observation. Réunis, ils forment un schéma conceptuel.

Dans la SDMX, les données sont traitées à l'aide de flux de données, qui comportent chacun un ensemble de données avec une structure. Ces métadonnées structurales sont représentées au moyen d'une définition de structure de données (DSD), qui peut être réutilisée d'un flux de données à un autre. Imaginons que le flux de données est un conteneur à données avec une structure commune (les sujets similaires sont généralement groupés, la structure étant fondée sur un modèle hypercube.

Un ensemble de dimensions sont utilisées pour définir la structure de données et le flux de données. Pour CCIE, les structures de données peuvent différer de l'une à l'autre. Certains concepts communs utilisés comme dimensions peuvent être :

• fréquence
• région géographique
• produit
• industrie
• période de référence.

Pour tenir à jour une liste contrôlée de codes, les valeurs permises pour chaque dimension sont conservées dans une liste de codes. Cela signifie, par exemple, que la liste de codes connectée à la dimension de fréquence comprendrait la liste de fréquences permises. Les listes de codes peuvent être utilisées par de nombreuses structures.

Chaque point de données a un identificateur unique appelé une clé, qui représente la combinaison des valeurs dans chaque dimension. L'ordre de la dimension dans la liste de dimensions est important pour produire la clé. La clé correspond à la liste de valeurs de dimension pour chaque dimension séparée par un point (.) et dresse la liste des dimensions selon l'ordre dans lequel elles apparaissent dans la liste de dimensions de la DSD. Par exemple, la clé « .CA.142.211 » représente le filtrage de l'ensemble de données par la région géographique = Canada (CA), le produit = Gaz naturel (142) et l'industrie = Extraction de pétrole et de gaz (211).

Une observation peut avoir des attributs qui y sont attachés, comme l'unité de mesure, les commentaires et les notes de bas de page.

SDMX peut être représentée au moyen de différents formats d'accès. En voici quelques exemples :

• JSON pour les données et les structures
• XML pour les données et les structures
• CSV pour les données

Service Web de données SDMX

Toutes les données stockées pour les profils de recensement peuvent être extraites à l'aide de la chaîne de requête décrite ci-dessous :

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

Définition de la syntaxe

protocol

Le service Web est offert sur Hypertext Transfer

Protocol (HTTP), http and https.

wsEntryPoint

Le point d'entrée du service Web est accessible au même emplacement que le point d'entrée des données et métadonnées SDMX, c.-à-d. « information-energie.canada.ca/sdmx/rest/ ».

resource

La ressource pour les requêtes est le data.

flowRef

Il s'agit d'une référence au flux de données décrivant les données qui doivent être renvoyées.

La syntaxe est l'identificateur de l'organisme maintenant le flux de données, suivi de l'identificateur du flux de données, puis de la version du flux de données, le tout séparé par une virgule (,).

Par exemple, dans la référence « STC, DF_38100139,1.0 », l'organisme est STC, il maintient le flux de données DF_38100139 et la version du flux de données est 1.0.

L'élément important ci-dessus est le nom du flux de données (DF_38100139).

Si la valeur du paramètre ne comprend qu'un élément, celui-ci est considéré comme l'identificateur du flux de données. L'identificateur de l'organisme prendra par défaut la valeur de tous ces éléments (all), alors que la valeur pour la version du flux de données prendra par défaut la dernière valeur (latest).

Si la valeur du paramètre comprend deux éléments, ceux-ci sont considérés comme l'identificateur de l'organisme et l'identificateur du flux de données. La version prendra par défaut la dernière valeur (latest)

key

Comme cela a été expliqué dans la section sur le modèle de données, la combinaison de dimensions permet d'identifier de manière unique des données statistiques. Une telle combinaison est connue sous le nom de clé de série dans SDMX et c'est ce qui est requis dans le paramètre de clé.

Par exemple, disons que les valeurs du dataflow DF_38100139 peuvent être identifiées de manière unique à l'aide des éléments suivants :

• la fréquence à laquelle elles sont mesurées (p. ex. tous les ans = code A)
• la région géographique mentionnée (p. ex. Canada = code 1)
• le flux physique (p. Utilisation directe d'énergie = code 1)
• un bien et service (produit) (p. ex. Services de soutient = code 14).

Pour produire une clé de série, vous devez prendre la valeur de chacune des dimensions (dans l'ordre dans lequel les dimensions sont définies dans la DSD) et les joindre avec un point (.). La clé de série pour l'exemple ci-dessus devient donc A.1.1.14.

L'utilisation de caractères de remplacement est prise en charge en omettant la valeur pour la dimension qui doit être remplacée. Par exemple, la clé de série suivante peut être utilisée pour extraire les données relatives à tous les flux physiques pour le Canada et les services de soutient : A.1..14.

Utiliser le caractère plus (+) comme opérateur « OU ». Par exemple, la clé suivante peut être utilisée pour extraire les données relatives à tous les flux physiques pour le Canada et les produits de services de soutient et les services de construction : A.1..14+15.

parameters

Dans cette chaîne de requête, les parameters sont définis comme suit :

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

Dans le cas du Centre canadien d'information sur l'énergie, les paramètres applicables sont le detail et le format.

detail

Pour préciser la quantité d'information que vous souhaitez que le service Web retourne, utiliser le paramètre detail.

Les options suivantes sont possibles :

• full : Toutes les données, y compris la série et les observations, et les attributs doivent être renvoyés. Il s'agit de la valeur par défaut.
• dataonly : Le message renvoyé exclura les attributs.
• serieskeysonly : Le message renvoyé inclura seulement la série. Les attributs et les observations seront exclus. Par exemple, cette option vous permettrait d'énumérer les séries qui correspondent à une requête en particulier, mais pas de renvoyer les données réelles.
• nodata : Le message renvoyé inclura la série ainsi que les attributs, mais pas les observations.

format

À l'aide du paramètre de format, vous pouvez indiquer au service Web de recevoir des données dans différents formats (voir aussi Négociation du contenu).

Les options possibles sont :

• csv
• jsondata

Exemples

1. Extraire les données en entier (Canada / tous les flux physiques / tous les produits) pour le flux de données DF_38100139.

https://information-energie.canada.ca/sdmx/rest/data/STC,DF_38100139/

2. Extraire les données pour les produits des Services de soutient (Canada/tous les flux physiques) pour le flux de données DF_38100139.

https://information-energie.canada.ca/sdmx/rest/data/STC,DF_38100139/A...14

Service Web de métadonnées SDMX

Toutes les métadonnées peuvent être extraites à l'aide de la chaîne de requête décrite ci-dessous :

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

Définition de la syntaxe

protocol

Le service Web est offert sur https.

wsEntryPoint

Le point d'entrée du service Web est accessible au même emplacement que le point d'entrée des métadonnées SDMX, c-à-d. « information-energie.canada.ca/sdmx/rest/ ».

resource

Les ressources suivantes sont prises en charge par le service Web : datastructure, codelist et dataflow. Veuillez noter qu'elles ne sont pas toutes utilisées actuellement.

agencyID

Les organisations définissant les métadonnées sont connues comme des organismes dans SDMX. Pour extraire un artefact, vous devez connaître l'identificateur de l'organisme qui le tient à jour. Les codes d'identification de l'organisme (agencyID) qui représentent Statistique Canada et CCIE sont respectivement STC et CCEI.

resourceID

L'identificateur de la ressource, comme CL_AREA pour la liste de régions géographiques, est mis à jour par l'organisme qui, dans ce cas, est STC.

version

Il s'agit de la version de l'artefact à renvoyer. Quand le numéro de version n'est pas fourni, la dernière version de la ressource est renvoyée.

detail

Vous pouvez préciser la quantité souhaitée de renseignements à retourner en utilisant le paramètre detail. Par exemple, il est possible de demander au service Web de ne renvoyer que les renseignements de base sur la ressource (c.-à-d. son ID, agencyID, version and name). Ceci est également connu dans SDMX comme un élément de remplacement.

Les valeurs permises sont les suivantes :

• full : Tous les renseignements disponibles pour tous les artefacts seront renvoyés. Il s'agit de la valeur par défaut.
• allstubs : Tous les artefacts seront renvoyés comme des éléments de remplacement
• referencestubs : Les artefacts indiqués seront renvoyés comme des éléments de remplacement.

references

En utilisant le paramètre references, vous pouvez demander au service Web de renvoyer (ou non) les artefacts indiqués par l'artefact à renvoyer (p. ex. les listes de codes et les concepts utilisés par la DSD correspondant à la requête). Vous pouvez également extraire les artefacts qui utilisent l'artefact correspondant (p. ex. les flux de données qui utilisent la DSD correspondant à la requête).

Les valeurs possibles sont les suivantes :

• none : Aucune référence ne sera renvoyée. Il s'agit de la valeur par défaut.
• parents&nbps;: Les artefacts qui utilisent l'artefact correspondant à la requête (p. ex. les flux de données qui utilisent la DSD correspondant à la requête) seront renvoyés.
• parentsandsiblings : Les artefacts qui utilisent l'artefact correspondant à la requête, ainsi que les artefacts indiqués par ces artefacts seront renvoyés.
• children : Les artefacts indiqués par l'artefact correspondant seront renvoyés (p. ex. les classifications des concepts et les listes de codes utilisés dans la DSD).
• descendants : Les références de références, jusqu'à n'importe quel niveau, seront également renvoyées.
• all : La combinaison de parentsandsiblings et descendants sera renvoyée.

Un type concret de ressource peut également être utilisé (p. ex. references=codelist).

Négociation du contenu

À l'aide du mécanisme de négociation de contenu HTTP, vous pouvez sélectionner la représentation de données à retourner. Vous pouvez également indiquer au service de comprimer les données à retourner.

Sélection du format

Les formats de données suivants sont pris en charge par le service Web :

• Formats de données :
  • SDMX-ML (SDMX-Meta Language) 2.1 Format de données générique : application/vnd.sdmx.genericdata+xml;version=2.1. Il s'agit de la valeur par défaut pour les requêtes de données.
  • SDMX-ML 2.1 Format de données propre à une structure : application/vnd.sdmx.structurespecificdata+xml;version=2.1
  • SDMX-JSON : application/vnd.sdmx.data+json;version=1.0.0-wd
  • CSV : text/csv
• Formats de métadonnées :
  • SDMX-ML Format de structure : application/vnd.sdmx.structure+xml;version=2.1
  • SDMX-JSON Format de structure : application/vnd.sdmx.structure+json;version=1.0

Les types de mimes génériques (application/json, application/xml) sont également pris en charge, mais ils indiqueront toujours la plus récente version des formats SDMX pris en charge par ces services Web. Cette version changera dans l'avenir chaque fois que de nouvelles versions des divers formats SDMX seront disponibles.

Par conséquent, il est fortement recommandé que les exécutants utilisent un des types de mime précisé ci-dessus plutôt qu'un mime générique, pour éviter tout problème quand de nouvelles versions des formats sont publiées.

Compression des résultats

Vous pouvez également activer la compression des données en utilisant le champ Accept-Encoding HTTP header. Les messages comprimés sont généralement beaucoup plus petits que les messages non comprimés, ce qui peut mener à des améliorations au moment du transfert de grandes quantités de données sur le réseau.

Codes d'état

Le service Web renvoie les codes d'état HTTP suivants.

Codes d'état HTTP

Code	État	Description
200	OK	Votre requête pourrait être traitée avec succès et les données avoir été renvoyées.
304	Aucune modification	Aucune modification depuis l'horodatage fourni dans l'en-tête If-Modified-Since.
400	Erreur de syntaxe	En cas de problème syntactique ou sémantique avec les paramètres que vous avez fournis, un code d'état HTTP 400 sera renvoyé.
404	Aucun résultat trouvé	Un code d'état HTTP 404 sera renvoyé si aucun résultat ne correspond à la requête.
406	Inacceptable	Si vous demandez une représentation de ressource que nous ne prenons pas en charge, le code d'état HTTP sera retourné. Reportez-vous à la section sur la négociation du contenu pour visualiser les représentations prises en charge.
500	Erreur interne du serveur	En cas de problème de notre côté, le code d'état HTTP 500 sera retourné. N'hésitez pas à essayer de nouveau plus tard ou à communiquer avec notre assistance téléphonique.
501	Aucune mise en œuvre	Ce service Web offre un sous-ensemble de la fonctionnalité offerte par la spécification du service Web SDMX RESTful. Quand vous utilisez une fonction que nous n'avons pas encore mise en œuvre, un code d'état HTTP 501 sera renvoyé.
503	Service non accessible	Si notre service Web est temporairement indisponible, un code d'état HTTP 503 sera renvoyé.

Conseils utiles

Le groupe de travail technique SDMX (anglais seulement)S'ouvre dans un nouveau onglet publie une liste utile de conseils et astuces pour les clients du service Web qui valent la peine d'être consultés.

Le groupe de travail technique SDMX (anglais seulement)S'ouvre dans un nouveau onglet a également publié un aide-mémoire de deux pages qui résume les principaux points de l'IPA SDMX 2.1 RESTful.

Si la documentation ne contient pas les renseignements dont vous avez besoin ou si vous avez des commentaires généraux ou de la rétroaction au sujet de notre service Web, veuillez nous contacterS'ouvre dans un nouveau onglet.

Tous les modèles de requêtes présentés dans le présent document peuvent également être exécutés à l'aide d'outils de ligne de commande comme curl ou wget :

wget -O data.xml \

--header="Accept:application/vnd.sdmx.structurespecificdata+xml;version=2.1" \

https://energy-information.canada.ca/sdmx/rest/data/STC,DF_38100139,1.0/A.1.1.14

curl -k -o data.xml \

--header "Accept:application/vnd.sdmx.structurespecificdata+xml;version=2.1" \

https://energy-information.canada.ca/sdmx/rest/data/STC,DF_38100139,1.0/A.1.1.14