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 remplacementreferencestubs
: 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 deparentsandsiblings
etdescendants
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
- SDMX-ML (SDMX-Meta Language) 2.1 Format de données générique :
- 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
- SDMX-ML Format de structure :
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.
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