Skip to contents

Changelog

Source: NEWS.md

canbank 0.3.0

Backend rewritten to use the JSON API

All requests now go to the Bank of Canada Valet API’s JSON endpoints rather than its CSV endpoints. The CSV responses are multi-section documents whose section markers vary by endpoint and by the dimensions a group happens to contain, and a number of groups are not served as CSV at all. Switching to JSON fixes both problems.

  • Data is now retrieved for 257 series groups that previously errored out — 17 that the CSV endpoint does not serve at all, and a further 120 whose CSV layout the section parser could not read (these failed with `n_max` must be a number, not an empty numeric vector). Empty series, such as AUC_BOND_S_PRICE, no longer error either.
  • API errors now surface the Bank of Canada’s own message, e.g. Bank of Canada API: Series NOT_A_REAL_SERIES not found. in place of downloaded length 0 != reported length 126.
  • get_boc_series() retrieves series in batches within a single request rather than one request per series.

Breaking changes

  • get_boc_series() and get_boc_series_group() now return dimension and dimension_value columns in place of the raw dimension key column, which varied by group (date, k, bond_id, …). Date, series, label, description, value and Value are unchanged.

  • Series groups no longer return rows for series/date combinations that hold no observation. Previously the rectangular CSV layout produced these as rows with a missing value.

  • Value, the numeric coercion of value, is dropped from the result when no observation in it is numeric. Some series hold ISINs, maturity codes or clock times, and previous versions returned a column of NA for them. The check is made on the assembled result, so a call that mixes such series with numeric ones keeps the column.

New arguments

  • quarter_convention on get_boc_series(), get_boc_series_group() and get_boc_all_series_last_date() chooses the day for observations the API reports as a quarter rather than a date, for example 1998Q3: "middle" (the default, and what previous versions produced), "start" or "end". The default can be set with options(canbank.quarter_convention = ...).

    Observations the API reports as a date are used as reported. The JSON endpoints resolve quarters themselves and are not consistent about it — most series are dated to the start of the quarter, some to its end, some to its third month — but that is the Bank’s own dating and the package no longer second-guesses it. Quarterly series that previous versions received as a 1998Q3 label and dated to the middle of the quarter will therefore now carry whatever date the API gives them.

  • order_dir on get_boc_series() and get_boc_series_group() passes the API’s order_dir parameter.

  • quiet on list_boc_series(), list_boc_series_groups(), get_boc_series_info() and get_boc_series_group_info().

Failing gracefully when the API is unavailable

  • Every exported function now emits a warning and returns NULL when the Bank of Canada API cannot be reached, refuses the request, or returns something that is not JSON. Previous versions raised an error. A call spanning several requests keeps whatever came back and only returns NULL when nothing did.
  • get_boc_series_group() continues to return a row holding only group_name for an individual group it could not read, as long as some other group in the same call succeeded.

Dependencies

  • curl and jsonlite are now required; readr and tidyr are no longer used.
  • The declared R dependency is now R (>= 3.5), matching what the imported packages actually require.