NAV
JSON XML CSV

Valet API

The Bank of Canada Valet Web Services offers programmatic access to global financial data disseminated via the Valet API.

This API allows users to retrieve financial data and information from the Bank of Canada (e.g. 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: Observations, Observations Groups, and 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. All routes are case insensitive. Each route requires at least one seriesNames or groupName. However, the format and query parameters of these routes are optional.

Formats

Example JSON Response (Formats):

            
        

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/IEXE0102/json
/observations/group/FX_RATES_DAILY/xml
/fx_rss/FXUSDCAD/csv

Example query: /observations/FXCADUSD/json

Observations

Description

Observations is a route that will return observations filtered by seriesNames. An observation is the recorded date and value of a series.

Syntax

Observations 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 query: /observations/FXUSDCAD/json?recent=5

Parameters

Formats

The format of Observations 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 5, 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 that, recent_interval cannot be used at the same time as the start_date and end_date parameters.

Response

An Observations 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
  • Observations:
    • date: The date of the observation
    • value: The value of the observation

Observations Groups

Description

Observations Groups is a route that will return a group of series filtered by groupName. A group of series includes all its observations within that group.

Syntax

Observations Groups requires one groupName to return the observations of 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 query: /observations/group/FX_RATES_DAILY/json?recent=5

Parameters

Formats

The format of Observations Groups 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 section for more information.

Response

An Observations Groups response in JSON, XML, or CSV will contain the following information:

  • Group Detail:
    • label: The title of the group
    • description: The description of the group or the group's source of information
    • link: The link to more information related to this 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
  • Observations:
    • date: The date of the observation
    • value: The value of the observation

Foreign Exchange Rates in RSS

Description

Foreign Exchange Rates in RSS is a route that will return 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 query: /fx_rss/FXUSDCAD

Parameters

Series Names

seriesNames is a comma separated list of one or more series names as 'FX[country1][country2]'. /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 exchanges 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

Status Code Response Message
500 An error has occurred. If this problem persists, please contact website@bankofcanada.ca.
404 The page you are looking for is unavailable.
400 Start date contains a value that is not allowed. Expected format is YYYY-MM-DD, e.g. 2001-01-27
400 End date contains a value that is not allowed. Expected format is YYYY-MM-DD, e.g. 2001-01-27
400 The End date must be greater than the Start date.
400 Bad output format (%format%) requested.
400 Bad recent observations request parameters, you can only specify one of recent, recent_weeks, recent_months, recent_years
400 Bad recent observations request parameters, must be numeric
400 Bad recent observations request parameters, you can not mix start_date or end_date with any of recent, recent_weeks, recent_months, recent_years
400 Bad recent observations request parameters, you cannot have a recent value less than one
404 Series %name% not found.
404 Group %name% not found.