Valet API

The Bank of Canada Valet Web Services offers programmatic access to global financial data. By using the Valet API, you can retrieve financial data and information from the Bank of Canada — such as daily exchange rates of the Canadian dollar against the European euro.

Formats

We provide data in JSON, XML, and CSV formats.

Routes

The Valet API offers these routes:

• Lists
• Series
• Series Groups
• Observations by Series
• Observations by Series Group
• Foreign Exchange Rates in RSS

The Base URL of each route is as follows:

https://www.bankofcanada.ca/valet

All routes shown below

• must be prefixed by the Base URL
• require at least one seriesNames, groupName or listName — but the format and query parameters of these routes are optional

Formats

Example JSON Response ():

A format is the file extension of a response returned by Valet. Valet can return data in JSON, XML, and CSV formats. The default is JSON. The format is specified by adding a file extension to the end of the request path.

/observations/seriesNames/format

Example query: /observations/FXCADUSD/json
/observations/group/FX_RATES_DAILY/xml


Lists

The Lists route provides a response containing the names of all available series, or all available series groups, depending on the value of listName.

Syntax

This route requires a listName to return a list. The syntax is as follows:

/lists/listName

Example JSON Response ():

Example query: /lists/groups

Parameters

List Name

listName is the set of data to return. The following values are valid: /lists/series
/lists/groups


Format

The format of a Lists response can be JSON, XML, or CSV. /lists/listName/json
/lists/listName/xml
/lists/listName/csv


Response

A Lists response returned in JSON, XML, or CSV will contain the following information:

• Terms and Conditions:
  • url: The url to the terms and conditions for using content produced by the Bank of Canada
• Series or Series Group: The list of available series or series groups
  • label: The title of the series or series group
  • link: The link to request the series or series group details

Series

The Series route provides a response containing the details associated with a seriesName.

Syntax

This route requires a seriesName to return a response. The syntax is as follows:

/series/seriesName

Example JSON Response ():

Example query: /series/FXAUDCAD

Parameters

Series Name

seriesName is the series details to be returned. /series/FXUSDCAD
/series/VO691346

Format

The format of a Series response can be JSON, XML, or CSV. /series/seriesName/json
/series/seriesName/xml
/series/seriesName/csv


Response

A Series response returned in JSON, XML, or CSV will contain the following information:

• Terms and Conditions:
  • url: The url to the terms and conditions for using content produced by the Bank of Canada
• Series Details: The details for the requested series
  • name: The id of the requested series
  • label: The title of the requested series
  • description: The description of the requested series

Series Groups

The Series Group route provides a response containing the details associated with a groupName and all the series it contains.

Syntax

This route requires a groupName to return a response. The syntax is as follows:

/groups/groupName

Example JSON Response ():

Example query: /groups/FX_RATES_DAILY

Parameters

Group Name

groupName is the series group details to be returned. /groups/FX_RATES_MONTHLY

Format

The format of a Series Group can be JSON, XML, or CSV. /groups/groupName/json
/groups/groupName/xml
/groups/groupName/csv

Response

A Series Group response returned in JSON, XML, or CSV will contain the following information:

• Terms and Conditions:
  • url: The url to the terms and conditions for using content produced by the Bank of Canada
• Group Details: The details for the requested series group
  • name: The id of the requested group
  • label: The title of the requested group
  • description: The description of the requested group
  • groupSeries: The series within the requested group
    • name: The id of the series
      • label: The title of the series
      • link: The link to the series details

Observations by Series

The Observations by Series route returns observations filtered by seriesNames. An observation is the recorded date and value of a series.

Syntax

Observations by Series requires at least one seriesNames to return the observations of a requested series. The format can be specified, but will default to JSON if not provided. An optional parameter query can specify the data within a certain date range. The syntax is as follows:

/observations/seriesNames/format?query

Example JSON Response ():

Example query: /observations/FXUSDCAD/json?recent=5

Parameters

Formats

The format of Observations by Series can be JSON, XML, or CSV. /observations/FXUSDCAD/json
/observations/FXUSDCAD/xml
/observations/FXUSDCAD/csv

Series Names

seriesNames is a comma separated list of one or more series names. /observations/FXUSDCAD
/observations/FXUSDCAD,A.AGRI


Query

A query is composed of a start date, end date, or both. This allows limiting the amount of data to be returned. For example, start_date=2016-05-09&end;_date=2016-05-12 would return all the observations of a given series between the dates of May 9, 2016 and May 12, 2016 inclusive.

Start and End Dates:

• start_date: A date formatted as YYYY-MM-DD. This filters the observations returned so they are all on or after the date specified.
• end_date: A date formatted as YYYY-MM-DD. This filters the observations returned so they are all on or before the date specified.

query: start_date, end_date, or both /observations/FXUSDCAD?start_date=2016-05-09
/observations/FXUSDCAD?end_date=2016-05-12
/observations/FXUSDCAD?start_date=2016-05-09&end;_date=2016-05-12


A query can also be expressed in terms of recent weeks, months or years. For example, recent_weeks=10 would return all the observations from 10 weeks ago to today.

Recent Interval:

• recent_interval=X: A time interval formatted as recent_[interval], where [interval] expects weeks, months, or years and X expects an integer. This filters the observations returned so they are all from X [interval] ago to today inclusive.

query: recent_interval

Returns the most recent X observations per series: /observations/FXUSDCAD?recent=X

Returns observations from the last X weeks for each series: /observations/FXUSDCAD?recent_weeks=X

Returns observations from the last X months for each series: /observations/FXUSDCAD?recent_months=X

Returns observations from the last X years for each series: /observations/FXUSDCAD?recent_years=X

NOTE: recent_interval cannot be used at the same time as the start_date and end_date parameters.

NOTE: Date related query parameters can only be used with time series.

Response

An Observations by Series response returned in JSON, XML, or CSV will contain the following information:

• Terms and Conditions:
  • url: The url to the terms and conditions for using content produced by the Bank of Canada
• Series Detail:
  • id: The id of the specific series
  • label: The label of the series
  • description: The description of the series
  • dimension: The dimension for this series e.g. date, category, etc.
    • key: Short name for the dimension
    • name: Name for the dimension
• Observations:
  • dimension: The dimension of the observation. Short key is used to define the field.
  • value: The value of the observation

Observations by Series Group

The Observations by Series Group route returns a group of series filtered by groupName. A group of series includes all observations of all series within that group.

Syntax

Observations by Series Group requires one groupName to return the observations of the series associated with the requested group. The format can be specified, but will default to JSON if not provided. An optional parameter query can specify the data within a certain date range. The syntax is as follows:

/observations/group/groupName/format?query

Example JSON Response ():

Example query: /observations/group/FX_RATES_DAILY/json?recent=5

Parameters

Formats

The format of Observations by Series Group can be JSON, XML, or CSV. /observations/FX_RATES_DAILY/json
/observations/FX_RATES_DAILY/xml
/observations/FX_RATES_DAILY/csv

Group Name

A groupName is a group of series bundled together for convenience. /observations/group/FX_RATES_DAILY
/observations/group/sdp-2012-8

Query

Refer to the Observations by Series section for more information.

Response

An Observations by Series Group response in JSON, XML, or CSV will contain the following information:

• Group Detail:
  • label: The title of the series group
  • description: The description of the series group or the series group's source of information
  • link: The link to more information related to this series group
• Terms and Conditions:
  • url: The url to the terms and conditions for using content produced by the Bank of Canada
• Series Detail:
  • id: The id of the specific series within this group
  • label: The label of the series
  • description: The description of the series
  • dimension: The dimension for this series e.g. date, category, etc.
    • key: Short name for the dimension
    • name: Name for the dimension
• Observations:
  • dimension: The dimension of the observation. Short key is used to define the field.
  • value: The value of the observation

Foreign Exchange Rates in RSS

The Foreign Exchange Rates in RSS route returns exchange rate observations filtered by seriesNames. An exchange rate observation is data that describes the exchange rate of two countries in a series.

Syntax

Foreign Exchange Rates in RSS requires at least one seriesNames to return the observations of a series in RSS format. This route always returns the single most recent observation per series. The syntax is as follows:

/fx_rss/seriesNames

Example RSS Response ():

Example query: /fx_rss/FXUSDCAD

Parameters

Series Names

seriesNames is a comma separated list of one or more series names as FX[currency1][currency2]. /fx_rss/FXUSDCAD
/fx_rss/FXUSDCAD,FXEURCAD


If provided, this limits the observations returned to a specific exchange rates series. If not provided, the route will return the most recent observation for all exchange rates.

Response

A Foreign Exchange Rates in RSS response returned in RSS will contain the following information:

• title: The title of the RSS feed
• link: A link to the Bank’s exchange rates page
• description: The description of the RSS feed
• items: The list of exchange rates observations
  • title: The exchange rate expressed as an equation
  • link: A link to the Bank’s exchange rates page
  • description: The description of the exchange rate between two countries
  • dc:date: The date of the observation
  • dc:language: The language of this information
  • cb:statistics: Provides the observation data in finer detail
    • cb:country: The country of interest
    • cb:exchangeRate: Information about the exchange rate
      • cb:value: The exchange rate between the two countries
      • cb:baseCurrency: The base currency of this observation
      • cb:targetCurrency: The target currency of this observation
      • cb:rateType: Type of exchange rate
      • cb:observationPeriod: The date of the observation and the frequency of the series

Errors

Example Response ():