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 (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/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 (Lists):

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
  • name: The id of series or group
  • 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 (Series):

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 (Series Groups):

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 (Observations by Series):

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 may contain a start date, end date, recent, or order direction parameters. 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, years or recent observations. For example, recent_weeks=10 would return all the observations from 10 weeks ago to today.

Recent Interval:

• 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. When interval is omitted, X recent observations are returned.

query: recent_interval

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

Returns last X observations 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.

Order direction:

• Whether to return observations in ascending or descending order. The order_dir parameter accepts one of the following two values: asc or desc.

query: order_dir

Returns observations per series in ascending order: /observations/FXUSDCAD?order_dir=asc

Returns observations per series in descending order: /observations/FXUSDCAD?order_dir=desc

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.
  • id: series id
  • value: The observation value for the series

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 (Observations by Series Group):

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/group/FX_RATES_DAILY/json
/observations/group/FX_RATES_DAILY/xml
/observations/group/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.
  • id: series id
  • value: The observation value for the series

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 accepts one seriesNames parameter. 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. The syntax is as follows:

/fx_rss/seriesNames

Example RSS Response (Foreign Exchange Rates in RSS):

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


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 (Errors):