`investpy.bonds`¶

investpy.bonds.get_bond_countries()¶

This function returns a listing with all the available countries from where bonds can be retrieved, so to let the user know which of them are available, since the parameter country is mandatory in every bond retrieval function. Also, not just the available countries, but the required name is provided since Investing.com has a certain country name standard and countries should be specified the same way they are in Investing.com.

Returns

The resulting list contains all the available countries with government bonds as indexed in Investing.com

Return type

list - countries

Raises

FileNotFoundError – raised when bond countries file was not found.
IOError – raised when bond countries file is missing or empty.

investpy.bonds.get_bond_historical_data(bond, from_date, to_date, as_json=False, order='ascending', interval='Daily')¶

This function retrieves historical data from the introduced bond from Investing.com. So on, the historical data of the introduced bond in the specified date range will be retrieved and returned as a pandas.DataFrame if the parameters are valid and the request to Investing.com succeeds. Note that additionally some optional parameters can be specified: as_json and order, which let the user decide if the data is going to be returned as a json or not, and if the historical data is going to be ordered ascending or descending (where the index is the date), respectively.

Parameters

bond (str) – name of the bond to retrieve historical data from.
from_date (str) – date formatted as dd/mm/yyyy, since when data is going to be retrieved.
to_date (str) – date formatted as dd/mm/yyyy, until when data is going to be retrieved.
as_json (bool, optional) – to determine the format of the output data, either a pandas.DataFrame if False and a json if True.
order (str, optional) – to define the order of the retrieved data which can either be ascending or descending.
interval (str, optional) – value to define the historical data interval to retrieve, by default Daily, but it can also be Weekly or Monthly.

Returns

The function returns a either a pandas.DataFrame or a json file containing the retrieved recent data from the specified bond via argument. The dataset contains the open, high, low and close for the selected bond on market days.

The resulting recent data, in case that the default parameters were applied, will look like:

Date || Open | High | Low | Close
-----||------|------|-----|-------
xxxx || xxxx | xxxx | xxx | xxxxx

but in case that as_json parameter was defined as True, then the output will be:

{
    name: name,
    historical: [
        {
            date: 'dd/mm/yyyy',
            open: x,
            high: x,
            low: x,
            close: x
        },
        ...
    ]
}

Return type

pandas.DataFrame or json

Raises

ValueError – raised whenever any of the introduced arguments is not valid or errored.
IOError – raised if bonds object/file was not found or unable to retrieve.
RuntimeError – raised if the introduced bond was not found or did not match any of the existing ones.
ConnectionError – raised if connection to Investing.com could not be established.
IndexError – raised if bond historical data was unavailable or not found in Investing.com.

Examples

>>> data = investpy.get_bond_historical_data(bond='Argentina 3Y', from_date='01/01/2010', to_date='01/01/2019')
>>> data.head()
            Open  High   Low  Close
Date
2011-01-03  4.15  4.15  4.15   5.15
2011-01-04  4.07  4.07  4.07   5.45
2011-01-05  4.27  4.27  4.27   5.71
2011-01-10  4.74  4.74  4.74   6.27
2011-01-11  4.30  4.30  4.30   6.56

investpy.bonds.get_bond_information(bond, as_json=False)¶

This function retrieves fundamental financial information from the specified bond. The retrieved information from the bond can be valuable as it is additional information that can be used combined with OHLC values, so to determine financial insights from the company which holds the specified bond.

Parameters

bond (str) – name of the bond to retrieve information from.
as_json (bool, optional) – optional argument to determine the format of the output data (dict or json).

Returns

The resulting pandas.DataFrame contains the information fields retrieved from Investing.com from the specified bond; it can also be returned as a dict, if argument as_json=True.

If any of the information fields could not be retrieved, that field/s will be filled with None values. If the retrieval process succeeded, the resulting dict will look like:

bond_information = {
    "1-Year Change": "46.91%",
    "52 wk Range": "-0.575 - 0.01",
    "Bond Name": "Spain 1Y",
    "Coupon": "None",
    "Maturity Date": "04/12/2020",
    "Prev. Close": -0.425,
    "Price": 100.417,
    "Price Open": 100.416,
    "Price Range": -100.481,
    "Todays Range": "-0.49 - -0.424"
}

Return type

pandas.DataFrame or dict- bond_information

Raises

ValueError – raised if any of the introduced arguments is not valid or errored.
FileNotFoundError – raised if bonds.csv file was not found or errored.
IOError – raised if bonds.csv file is empty or errored.
RuntimeError – raised if scraping process failed while running.
ConnectionError – raised if the connection to Investing.com errored (did not return HTTP 200)

investpy.bonds.get_bond_recent_data(bond, as_json=False, order='ascending', interval='Daily')¶

This function retrieves recent historical data from the introduced bond from Investing.com. So on, the recent data of the introduced bond will be retrieved and returned as a pandas.DataFrame if the parameters are valid and the request to Investing.com succeeds. Note that additionally some optional parameters can be specified: as_json and order, which let the user decide if the data is going to be returned as a json or not, and if the recent data is going to be ordered ascending or descending (where the index is the date), respectively.

Parameters

bond (str) – name of the bond to retrieve recent historical data from.
as_json (bool, optional) – to determine the format of the output data, either a pandas.DataFrame if False and a json if True.
order (str, optional) – to define the order of the retrieved data which can either be ascending or descending.
interval (str, optional) – value to define the historical data interval to retrieve, by default Daily, but it can also be Weekly or Monthly.

Returns

The function can return either a pandas.DataFrame or a json object, containing the retrieved recent data of the specified bond. So on, the resulting dataframe contains the open, high, low and close values for the selected bond on market days.

The resulting recent data, in case that the default parameters were applied, will look like:

Date || Open | High | Low | Close
-----||------|------|-----|-------
xxxx || xxxx | xxxx | xxx | xxxxx

but in case that as_json parameter was defined as True, then the output will be:

{
    name: name,
    recent: [
        {
            date: 'dd/mm/yyyy',
            open: x,
            high: x,
            low: x,
            close: x
        },
        ...
    ]
}

Return type

pandas.DataFrame or json

Raises

ValueError – raised whenever any of the introduced arguments is not valid or errored.
IOError – raised if bonds object/file was not found or unable to retrieve.
RuntimeError – raised if the introduced bond was not found or did not match any of the existing ones.
ConnectionError – raised if connection to Investing.com could not be established.
IndexError – raised if bond historical data was unavailable or not found in Investing.com.

Examples

>>> data = investpy.get_bond_recent_data(bond='Argentina 3Y')
>>> data.head()
              Open    High     Low   Close
Date
2019-09-23  52.214  52.214  52.214  52.214
2019-09-24  52.323  52.323  52.323  52.323
2019-09-25  52.432  52.432  52.432  52.432
2019-09-26  52.765  52.765  52.765  52.765
2019-09-27  52.876  52.876  52.876  52.876

investpy.bonds.get_bonds(country=None)¶

This function retrieves all the bonds data stored in bonds.csv file, which previously was retrieved from Investing.com. Since the resulting object is a matrix of data, the bonds data is properly structured in rows and columns, where columns are the bond data attribute names. Additionally, country filtering can be specified, which will make this function return not all the stored bond data, but just the data of the bonds from the introduced country.

Parameters

country (str, optional) – name of the country to retrieve all its available bonds from.

Returns

The resulting pandas.DataFrame contains all the bond data from the introduced country if specified, or from every country if None was specified, as indexed in Investing.com from the information previously retrieved by investpy and stored on a csv file.

So on, the resulting pandas.DataFrame will look like:

country | name | full name
--------|------|-----------
xxxxxxx | xxxx | xxxxxxxxx

Return type

pandas.DataFrame - bonds_df

Raises

ValueError – raised whenever any of the introduced arguments is not valid.
FileNotFoundError – raised when bonds file was not found.
IOError – raised when bond countries file is missing or empty.

investpy.bonds.get_bonds_dict(country=None, columns=None, as_json=False)¶

This function retrieves all the bonds information stored in the bonds.csv file and formats it as a Python dictionary which contains the same information as the file, but every row is a dict and all of them are contained in a list. Note that the dictionary structure is the same one as the JSON structure. Some optional paramaters can be specified such as the country, columns or as_json, which are a filtering by country so not to return all the bonds but just the ones from the introduced country, the column names that want to be retrieved in case of needing just some columns to avoid unnecessary information load, and whether the information wants to be returned as a JSON object or as a dictionary; respectively.

Parameters

country (str, optional) – name of the country to retrieve all its available bonds from.
columns (list, optional) – column names of the bonds data to retrieve, can be: <country, name, full_name>
as_json (bool, optional) – if True the returned data will be a json object, if False, a list of dict.

Returns

The resulting list of dict contains the retrieved data from every bond as indexed in Investing.com from the information previously retrieved by investpy and stored on a csv file.

In case the information was successfully retrieved, the list of dict will look like:

bonds_dict = {
    'country': country,
    'name': name,
    'full_name': full_name,
}

Return type

list of dict OR json - bonds_dict

Raises

ValueError – raised whenever any of the introduced arguments is not valid.
FileNotFoundError – raised when bonds file was not found.
IOError – raised when bond countries file is missing or empty.

investpy.bonds.get_bonds_list(country=None)¶

This function retrieves all the bond names as stored in bonds.csv file, which contains all the data from the bonds as previously retrieved from Investing.com. So on, this function will just return the government bond names which will be one of the input parameters when it comes to bond data retrieval functions from investpy. Additionally, note that the country filtering can be applied, which is really useful since this function just returns the names and in bond data retrieval functions both the name and the country must be specified and they must match.

Parameters

country (str, optional) – name of the country to retrieve all its available bonds from.

Returns

The resulting list contains the all the bond names from the introduced country if specified, or from every country if None was specified, as indexed in Investing.com from the information previously retrieved by investpy and stored on a csv file.

In case the information was successfully retrieved, the list of bond names will look like:

bonds_list = ['Argentina 1Y', 'Argentina 3Y', 'Argentina 5Y', 'Argentina 9Y', ...]

Return type

list - bonds_list

Raises

ValueError – raised whenever any of the introduced arguments is not valid.
FileNotFoundError – raised when bonds file was not found.
IOError – raised when bond countries file is missing or empty.

investpy.bonds.get_bonds_overview(country, as_json=False)¶

This function retrieves an overview containing all the real time data available for the government bonds from a country, such as the names, symbols, current value, etc. as indexed in Investing.com. So on, the main usage of this function is to get an overview on the government bonds from a country, so to get a general view.

Parameters

country (str) – name of the country to retrieve the government bonds overview from.
as_json (bool, optional) – optional argument to determine the format of the output data (pandas.DataFrame or json).

Returns

The resulting pandas.DataFrame contains all the data available in Investing.com of the government bonds from a country in order to get an overview of it.

If the retrieval process succeeded, the resulting pandas.DataFrame should look like:

country | name | last | last_close | high | low | change | change_percentage
--------|------|------|------------|------|-----|--------|-------------------
xxxxxxx | xxxx | xxxx | xxxxxxxxxx | xxxx | xxx | xxxxxx | xxxxxxxxxxxxxxxxx

Return type

pandas.DataFrame - bonds_overview

Raises

ValueError – raised if any of the introduced arguments is not valid or errored.
FileNotFoundError – raised if bonds.csv file is missing.
IOError – raised if data could not be retrieved due to file error.
RuntimeError – raised either if the introduced country does not match any of the listed ones or if no overview results could be retrieved from Investing.com.
ConnectionError – raised if GET requests does not return 200 status code.

investpy.bonds.search_bonds(by, value)¶

This function searches bonds by the introduced value for the specified field. This means that this function is going to search if there is a value that matches the introduced one for the specified field which is the bonds.csv column name to search in. Available fields to search bonds are ‘name’ or ‘full_name’.

Parameters

by (str) – name of the field to search for, which is the column name which can be: ‘name’ or ‘full_name’.
value (str) – value of the field to search for, which is the value that is going to be searched.

Returns

The resulting pandas.DataFrame contains the search results from the given query, which is any match of the specified value in the specified field. If there are no results for the given query, an error will be raised, but otherwise the resulting pandas.DataFrame will contain all the available bonds that match the introduced query.

Return type

pandas.DataFrame - search_result

Raises

ValueError – raised if any of the introduced parameters is not valid or errored.
FileNotFoundError – raised if bonds.csv file is missing.
IOError – raised if data could not be retrieved due to file error.
RuntimeError – raised if no results were found for the introduced value in the introduced field.

investpy.bonds¶

`investpy.bonds`¶