pyvalet

Simple, pandas integrated API wrapper for the Bank of Canada Valet API.

The Valet API provides programmatic access to all of the data made publicly available by the Bank of Canada, including daily foreign exchange rates, measures of geopolitical risk, mortgage refinancing information and bond rates, just to name a few.

The full Valet API documentation page can be found here.

Installation:

To install this package, you can find the latest stable release on PyPi

pip install pyvalet

Otherwise, you can install from source by first cloning the GitHub repo:

git clone https://github.com/tylercroberts/pyvalet.git

cd pyvalet
pip install -e .

If you wish to run tests, or build documentation, be sure to put [tests], or [docs] after the ..

pip install -e ".[tests]"
pip install -e ".[docs]"

Getting Started:

To get started using pyvalet, simply open up a new python file and type:

from pyvalet import ValetInterpreter

vi = ValetInterpreter()

This will be your interface with all the features of pyvalet.

Series and Group Lists:

vi.list_series()

vi.list_groups()

These two commands will provide you with a pandas DataFrame containing all possible series, or groups to explore using the Valet API. The three fields output are 'name', 'label' and 'link'.

The first time you run these commands, the ValetInterpreter will cache them so there is no need to assign the output, unless you plan to filter these lists.

They can be accessed through:

vi.series_dict

vi.groups_dict

Series and Group Details:

To get more details about these series or groups, the get_series_detail() or get_group_detail() methods are available

df = vi.get_series_detail("FXUSDCAD", response_format='csv')

df_group, df_series = vi.get_group_detail("FX_RATES_DAILY", response_format='csv')

The output of .get_series_detail() is a pandas DataFrame containing, among other things, the name and description of a given series.

The output of .get_group_detail() is one pandas Series, and one DataFrame. The Series containing details about the group itself, and the DataFrame containing the same information about all series in the group.

Series and Group Observations:

Diving even deeper, you can pull observations from these series or groups using the get_series_observations() and get_groups_observations() methods.

df_series, df = vi.get_series_observations("FXUSDCAD", response_format='csv')
df = vi.get_group_observations("FX_RATES_DAILY", response_format='csv')

Additional keyword arguments can be passed to alter the query. See the docstrings for more information.

Like the methods for group details, the output of get_series_observations() and get_groups_observations is two pandas DataFrames, The first contains the details for either the series or group queried, and the second contains the observations themselves.

Alternatively, for any of the series or group methods, you can pass response_format='json' to recieve dictionaries instead of DataFrames.

RSS Feed for FX Rates:

pyvalet also offers an interface for pulling RSS feeds from the Valet API.

vi.get_fx_rss("FXUSDCAD")

This command will accept any series name as an argument, and returns an XML string containing the RSS feed.

Logging:

If you are encountering issues with pyvalet. You can enable debugging mode by passing a logging handler to the logger argument when instantiating the ValetInterpreter object. This will output DEBUG level messages. It was tested using the loguru package, but the base logging package, configured with a handler should work as well.

Contributing:

You can run tests from the directory root with pytest. This will also generate a coverage report. Please be sure to write tests to cover any new code.

The documentation can be built from within the docs directory. It will use any .rst files found within the source subfolder to generate doc pages. If any new pages are added, you will need to also update index.rst so they will show up in the generated HTML.

Please see CONTRIBUTING and CODE_OF_CONDUCT for more details.