Interface Valet

Les services Web Valet de la Banque du Canada permettent d’accéder, grâce à la programmation informatique, à des données financières internationales. En utilisant l’interface Valet, vous pouvez extraire les données et les informations financières publiées par la Banque du Canada : par exemple, le taux de change quotidien dollar canadien/euro.

Formats

Les données sont fournies aux formats JSON, XML et CSV.

Routes

Vous trouverez dans l'interface Valet les routes suivantes :

• Listes
• Séries
• Groupes de séries
• Observations par série
• Observations par groupe de séries
• Taux de change – fils RSS

L’URL racine (préfixe) de chaque route est :

https://www.banqueducanada.ca/valet

Toutes les routes indiquées ci-après…

• doivent être précédées de l’URL racine;
• nécessitent au moins un nom de série (seriesNames), de groupe (groupName) ou de liste (listName), mais le format et les paramètres de la requête (query) sont facultatifs.

Formats

Exemple de résultats au format JSON (Formats):

On entend par format le format de présentation des données regroupées par Valet dans le fichier de résultats. Il est indiqué dans l’extension du nom de fichier. Valet peut présenter les données au format JSON, XML ou CSV. JSON est le format implicite. Pour préciser le format désiré, il suffit d’ajouter l’extension correspondante à la fin de la requête.

/observations/seriesNames/format

Exemples de requête : /observations/FXCADUSD/json
/observations/group/FX_RATES_DAILY/xml


Listes

Cette route permet d’obtenir les noms de toutes les séries disponibles, ou de tous les groupes de séries, en fonction de la valeur du nom de liste (listName).

Syntaxe

Pour obtenir une liste, la route doit comprendre un nom de liste (listName). La syntaxe est la suivante :

/lists/listName

Exemple de résultats au format JSON (Listes):

Exemple de requête : /lists/series

Paramètres

Nom de la liste

listName donne accès à l’ensemble de données recherché. Les valeurs suivantes sont valides : /lists/series
/lists/groups


Format

Les listes sont présentées au format JSON, XML ou CSV : /lists/listName/json
/lists/listName/xml
/lists/listName/csv


Réponse

Les réponses à ce type de requête sont présentées au format JSON, XML ou CSV et accompagnées des précisions suivantes :

• Modalités :
  • url : url des modalités d’utilisation du contenu produit par la Banque du Canada
• Séries ou groupe de séries : liste de séries ou de groupes de séries disponibles
  • Name : code d’identification de la série ou du groupe
    • label : titre de la série ou du groupe de séries
    • description : description de la série ou du groupe de séries
    • link : lien permettant de faire une requête pour obtenir des détails concernant une série ou un groupe de séries

Séries

Cette route permet d’obtenir les détails associés à un nom de série (seriesName).

Syntaxe

Pour obtenir une liste, la route doit comprendre un nom de série (seriesName). La syntaxe est la suivante :

/series/seriesName

Exemple de résultats au format JSON (Séries):

Exemple de requête : /series/FXAUDCAD

Paramètres

Nom de la série

seriesName donne accès aux détails concernant la série demandée. /series/FXAUDCAD
/series/V0691346

Format

Les séries sont présentées au format JSON, XML ou CSV : /series/seriesName/json
/series/seriesName/xml
/series/seriesName/csv


Réponse

Les réponses à ce type de requête sont présentées au format JSON, XML ou CSV et accompagnées des précisions suivantes :

• Modalités :
  • url : url des modalités d’utilisation du contenu produit par la Banque du Canada
• Détails de la série : détails de la série demandée
  • name : code d’identification de la série demandée
  • label : titre de la série demandée
  • description : description de la série demandée

Groupes de séries

Cette route permet d’obtenir tous les détails associés à un nom de groupe (groupName) et toutes les séries qu’il contient.

Syntaxe

Pour obtenir une liste, la route doit comprendre un nom de groupe (groupName). La syntaxe est la suivante :

/groups/groupName

Exemple de résultats au format JSON (Groupes de séries):

Exemple de requête : /groups/FX_RATES_DAILY

Paramètres

Nom de groupe

groupName donne accès aux détails concernant le groupe de séries voulu. /groups/FX_RATES_MONTHLY

Format

Les groupes de séries sont présentées au format JSON, XML ou CSV : /groups/groupName/json
/groups/groupName/xml
/groups/groupName/csv


Réponse

Les réponses à ce type de requête sont présentées au format JSON, XML ou CSV et accompagnées des précisions suivantes :

• Modalités :
  • url : url des modalités d’utilisation du contenu produit par la Banque du Canada
• Détails sur le groupe : détails sur le groupe de séries demandé
  • name : code d’identification du groupe demandé
  • label : titre du groupe demandé
  • description : description du groupe demandé
  • groupSeries : série du groupe demandé
  • name : code d’identification de la série
  • label : titre de la série
  • link : lien vers les détails de la série

Observations par série

La route des observations par série permet d’obtenir des résultats filtrés par nom de série (seriesNames). Une observation comprend la date d’enregistrement et la valeur d'une série.

Syntaxe

Il faut indiquer au moins un nom de série (seriesNames) pour obtenir les observations de la série voulue. Si l’on ne précise pas de format, les données seront présentées implicitement au format JSON. On peut aussi utiliser un paramètre de requête (query) comme la période concernée, et cela, à l’aide de la syntaxe suivante :

/observations/seriesNames/format?query

Exemple de résultats au format JSON (Observations par série):

Exemple de requête : /observations/FXUSDCAD/json?recent=5

Paramètres

Formats

Les observations par série sont présentées au format JSON, XML ou CSV. /observations/FXUSDCAD/json
/observations/FXUSDCAD/xml
/observations/FXUSDCAD/csv

Noms de série

Le paramètre seriesNames donne une liste des noms de série séparés par une virgule. /observations/FXUSDCAD
/observations/FXUSDCAD,A.AGRI


Requête

Une requête (query) peut comprendre une date de début ou une date de fin, ou des paramètres récents, ce qui permet de limiter le nombre de résultats. Par exemple, la requête start_date=2016-05-09&end_date=2016-05-12 donnerait toutes les observations d’une série enregistrées du 9 au 12 mai 2016 inclusivement.

Dates de début et de fin :

• start_date: Date au format AAAA-MM-JJ. Ce paramètre permet de filtrer les résultats de sorte qu’ils ne comprennent que les observations enregistrées à partir de la date précisée.
• end_date: Date au format AAAA-MM-JJ. Ce paramètre permet de filtrer les résultats de sorte qu’ils ne comprennent que les observations enregistrées jusqu’à la date précisée.

query : start_date, end_date ou une combinaison des deux /observations/FXUSDCAD?start_date=2019-05-09
/observations/FXUSDCAD?end_date=2020-05-12
/observations/FXUSDCAD?start_date=2019-05-09&end_date=2020-05-12


Une requête peut aussi porter sur une période récente (exprimée en semaines, mois ou années). Par exemple, la requête recent_weeks=10 donnerait toutes les observations enregistrées depuis les dix dernières semaines.

Intervalle récent :

• Un intervalle de temps exprimé de la façon suivante : recent_[intervalle]=X, où l’intervalle correspond à des semaines, des mois ou des années, et X est un nombre entier. Ce paramètre permet de filtrer les observations de sorte qu’elles ne comprendront plus que les X derniers [intervalles] précisés (date de requête incluse). Si l’intervalle n’est pas précisé, le résultat comprend X observations récentes.

query : recent_[intervalle]

Exemple d’utilisation pour obtenir les X observations les plus récentes d’une série donnée : /observations/FXUSDCAD?recent=X

Exemple d’utilisation pour obtenir les observations des X dernières semaines d’une série donnée : /observations/FXUSDCAD?recent_weeks=X

Exemple d’utilisation pour obtenir les observations des X derniers mois d’une série donnée : /observations/FXUSDCAD?recent_months=X

Exemple d’utilisation pour obtenir les observations des X dernières années d’une série donnée : /observations/FXUSDCAD?recent_years=X

NOTA : Dans une requête, le paramètre recent _[intervalle] ne peut pas être utilisé en même temps que les paramètres start_date et end_date.

NOTA : Les paramètres de la requête relatifs à la date ne peuvent être utilisés qu’avec les séries chronologiques.

Ordre :

• Les observations peuvent être présentées en ordre croissant ou décroissant. Le paramètre order_dir accepte l’une des deux valeurs suivantes : asc ou desc.

query: order_dir

Présente les observations d’une série donnée en ordre croissant : /observations/FXUSDCAD?order_dir=asc

Présente les observations d’une série donnée en ordre décroissant : /observations/FXUSDCAD?order_dir=desc

Réponse

Les réponses à ce type de requête sont présentées au format JSON, XML ou CSV et accompagnées des précisions suivantes :

• Modalités :
  • url : url des modalités d’utilisation du contenu produit par la Banque du Canada
• Détails sur la série :
  • id : code d’identification de la série
  • label : titre de la série
  • description : description de chaque série
  • dimension : éléments de la série, par exemple la date ou la catégorie
    • Key : nom abrégé de la dimension
    • Name : nom de la dimension
• Observations :
  • dimension : dimension de l’observation. La clé sert à définir le champ
  • id : code d’identification de la série
    • value : valeur de l’observation relative à la série

Observations par groupe de séries

Les observations par groupe de séries permettent d’obtenir un groupe de séries filtrées par nom de groupe (groupName). Un groupe de séries comprend toutes les observations relatives aux séries relevant de ce groupe.

Syntaxe

Il faut indiquer au moins un nom de groupe (groupName) pour obtenir les observations de la série associées au groupe demandé. Si l’on ne précise pas de format, les données seront présentées implicitement au format JSON. On peut aussi utiliser un paramètre de requête (query) comme la période concernée, et cela, à l’aide de la syntaxe suivante :

/observations/group/groupName/format?query

Exemple de résultats au format JSON (Observations par groupe de séries):

Exemple de requête : /observations/group/FX_RATES_DAILY/json?recent=5

Paramètres

Formats

Les observations par groupe de séries sont présentées au format JSON, XML ou CSV. /observations/group/FX_RATES_DAILY/json
/observations/group/FX_RATES_DAILY/xml
/observations/group/FX_RATES_DAILY/csv

Nom de groupe

Un nom de groupe (groupName) correspond à un groupe de séries réunies pour en faciliter le traitement. /observations/group/FX_RATES_DAILY
/observations/group/sdp-2012-8

Requête

Pour en savoir plus, consultez la section Observations par série.

Réponse

Les réponses à ce type de requête sont présentées au format JSON, XML ou CSV et accompagnées des précisions suivantes :

• Détails sur le groupe:
  • label : titre du groupe de la série
  • description : description du groupe de la série ou de sa source d’information
  • link : lien vers de plus amples renseignements sur le groupe de séries en question
• Modalités :
  • url : url des modalités d’utilisation du contenu produit par la Banque du Canada
• Détails sur la série :
  • id : code d’identification de chaque série relevant du groupe en question
  • label : titre de la série
  • description : description de chaque série
  • dimension : éléments de la série, par exemple la date ou la catégorie
    • Key : nom abrégé de la dimension
    • Name : nom de la dimension
• Observations :
  • dimension : dimension de l’observation. La clé sert à définir le champ
  • id : code d’identification de la série
    • value : valeur de l’observation relative à la série

Taux de change – fils RSS

La route Taux de change – fils RSS permet d’obtenir des observations sur les taux de change filtrés par nom de série (seriesNames). Les taux de change sont bilatéraux, c’est-à-dire que les observations d’une série donnée concernent les taux de change entre deux monnaies.

Syntaxe

Il est possible d’indiquer un nom de série (seriesNames) pour limiter les résultats à une série de taux de change donnée. S’il n’est pas précisé, la route produira comme résultats la plus récente observation pour chaque série existante. La syntaxe est la suivante :

/fx_rss/seriesNames

Exemple de résultats RSS (Taux de change – fils RSS):

Exemple de requête : /fx_rss/FXUSDCAD

Paramètres

Noms de série

Le paramètre seriesNames donne une liste de noms de série séparés par une virgule, sous la forme FX[monnaie1][monnaie2]. /fx_rss/FXUSDCAD
/fx_rss/FXUSDCAD,FXEURCAD


Ce paramètre facultatif permet de limiter les résultats à une série de taux de change. S’il n’est pas précisé, la requête donnera comme résultats la plus récente observation pour chaque série existante.

Réponse

Les réponses à ce type de requête comprennent les renseignements suivants :

• title : titre du fil RSS
• link : lien vers la page Web de la Banque du Canada relative aux taux de change
• description : description du fil RSS
• items : liste des taux de change observés
  • title : taux de change exprimé sous forme d’équation
  • link : lien vers la page Web de la Banque du Canada relative aux taux de change
  • description : description du taux de change entre deux monnaies
  • dc:date : date d’observation
  • dc:language : langue dans laquelle sont présentés les renseignements
  • cb:statistics : précisions sur les données observées
    • cb:country : pays concerné
    • cb:exchangeRate : information sur le taux de change
      • cb:value : taux de change entre deux monnaies
      • cb:baseCurrency : monnaie de base
      • cb:targetCurrency : monnaie cible
      • cb:rateType : type de taux de change
      • cb:observationPeriod : date d’observation et fréquence de la série

Erreurs

Exemple de résultats (Erreurs):