investpy.etfs

investpy.etfs.get_etf_countries()

This function retrieves all the available countries to retrieve etfs from, as the listed countries are the ones indexed on Investing.com. The purpose of this function is to list the countries which have available etfs according to Investing.com data, so to ease the etf retrieval process of a particular country.

Returns

The resulting list contains all the countries listed on Investing.com with etfs available to retrieve data from.

In the case that the file reading of etf_countries.csv which contains the names and codes of the countries with etfs was successfully completed, the resulting list will look like:

countries = ['australia', 'austria', 'belgium', 'brazil', ...]

Return type

list - countries

Raises

FileNotFoundError – raised when etf_countries.csv file was not found.

investpy.etfs.get_etf_historical_data(etf, country, from_date, to_date, stock_exchange=None, as_json=False, order='ascending', interval='Daily')

This function retrieves historical data from the introduced etf from Investing.com via Web Scraping on the introduced date range. The resulting data can it either be stored in a pandas.DataFrame or in a json object with ascending or descending order.

Parameters

  • etf (str) – name of the etf to retrieve recent historical data from.

  • country (str) – name of the country from where the etf is.

  • from_date (str) – date as str formatted as dd/mm/yyyy, from where data is going to be retrieved.

  • to_date (str) – date as str formatted as dd/mm/yyyy, until where data is going to be retrieved.

  • as_json (bool, optional) – to determine the format of the output data (pandas.DataFrame or json).

  • order (str, optional) – optional argument to define the order of the retrieved data (ascending, asc or descending, desc).

  • 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 either a pandas.DataFrame or a json file containing the retrieved recent data from the specified etf via argument. The dataset contains the open, high, low and close values for the selected etf on market days.

The returned data is case we use default arguments will look like:

Date || Open | High | Low | Close | Volume | Currency | Exchange
-----||------|------|-----|-------|--------|----------|---------
xxxx || xxxx | xxxx | xxx | xxxxx | xxxxxx | xxxxxxxx | xxxxxxxx

but if we define as_json=True, then the output will be:

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

Return type

pandas.DataFrame or json

Raises

  • ValueError – raised whenever any of the arguments is not valid or errored.

  • IOError – raised if etfs object/file not found or unable to retrieve.

  • RuntimeError – raised if the introduced etf does not match any of the indexed ones.

  • ConnectionError – raised if GET requests does not return 200 status code.

  • IndexError – raised if etf information was unavailable or not found.

Examples

>>> data = investpy.get_etf_historical_data(etf='bbva accion dj eurostoxx 50', country='spain', from_date='01/01/2010', to_date='01/01/2019')
>>> data.head()
             Open   High    Low  Close  Volume Currency Exchange
Date
2011-12-07  23.70  23.70  23.70  23.62    2000      EUR   Madrid
2011-12-08  23.53  23.60  23.15  23.04     599      EUR   Madrid
2011-12-09  23.36  23.60  23.36  23.62    2379      EUR   Madrid
2011-12-12  23.15  23.26  23.00  22.88   10695      EUR   Madrid
2011-12-13  22.88  22.88  22.88  22.80      15      EUR   Madrid
investpy.etfs.get_etf_information(etf, country, as_json=False)

This function retrieves fundamental financial information from the specified ETF. The retrieved information from the ETF 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 ETF.

Parameters

  • etf (str) – name of the ETF to retrieve recent historical data from.

  • country (str) – name of the country from where the ETF is.

  • 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 ETF; 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:

etf_information = {
    "1-Year Change": "21.83%",
    "52 wk Range": "233.76 - 320.06",
    "Asset Class": "Equity",
    "Average Vol. (3m)": 59658771.0,
    "Beta": 1.01,
    "Dividend Yield": "1.73%",
    "Dividends (TTM)": 4.03,
    "ETF Name": "SPDR S&P 500",
    "Market Cap": 296440000000.0,
    "Open": 319.25,
    "Prev. Close": 317.27,
    "ROI (TTM)": "- 0.46%",
    "Shares Outstanding": 934132116.0,
    "Todays Range": "319.18 - 320.06",
    "Total Assets": 167650000000.0,
    "Volume": 27928710.0
}

Return type

pandas.DataFrame or dict- etf_information

Raises

  • ValueError – raised if any of the introduced arguments is not valid or errored.

  • FileNotFoundError – raised if etfs.csv file was not found or errored.

  • IOError – raised if etfs.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.etfs.get_etf_recent_data(etf, country, stock_exchange=None, as_json=False, order='ascending', interval='Daily')

This function retrieves recent historical data from the introduced etf from Investing via Web Scraping. The resulting data can it either be stored in a pandas.DataFrame or in a json file, with ascending or descending order.

Parameters

  • etf (str) – name of the etf to retrieve recent historical data from.

  • country (str) – name of the country from where the etf is.

  • as_json (bool, optional) – optional argument to determine the format of the output data (pandas.DataFrame or json).

  • order (str, optional) – optional argument to define the order of the retrieved data (ascending, asc or descending, desc).

  • 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 either a pandas.DataFrame or a json file containing the retrieved recent data from the specified etf via argument. The dataset contains the open, high, low and close values for the selected etf on market days.

The returned data is case we use default arguments will look like:

Date || Open | High | Low | Close | Volume | Currency | Exchange
-----||------|------|-----|-------|--------|----------|---------
xxxx || xxxx | xxxx | xxx | xxxxx | xxxxxx | xxxxxxxx | xxxxxxxx

but if we define as_json=True, then the output will be:

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

Return type

pandas.DataFrame or json

Raises

  • ValueError – raised whenever any of the arguments is not valid or errored.

  • IOError – raised if etfs object/file not found or unable to retrieve.

  • RuntimeError – raised if the introduced etf does not match any of the indexed ones.

  • ConnectionError – raised if GET requests does not return 200 status code.

  • IndexError – raised if etf information was unavailable or not found.

Examples

>>> data = investpy.get_etf_recent_data(etf='bbva accion dj eurostoxx 50', country='spain')
>>> data.head()
              Open    High    Low   Close  Volume Currency Exchange
Date
2020-04-09  28.890  29.155  28.40  28.945   20651      EUR   Madrid
2020-04-14  29.345  30.235  28.94  29.280   14709      EUR   Madrid
2020-04-15  29.125  29.125  28.11  28.130   14344      EUR   Madrid
2020-04-16  28.505  28.590  28.08  28.225   17662      EUR   Madrid
2020-04-17  29.000  29.325  28.80  28.895   19578      EUR   Madrid
investpy.etfs.get_etfs(country=None)

This function retrieves all the available etfs indexed on Investing.com, already stored on etfs.csv. This function also allows the users to specify which country do they want to retrieve data from or if they want to retrieve it from every listed country; so on, all the indexed etfs will be returned.

Parameters

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

Returns

The resulting pandas.DataFrame contains all the etfs basic information stored on etfs.csv, since it was previously retrieved by investpy. Unless the country is specified, all the available etfs indexed on Investing.com is returned, but if it is specified, just the etfs from that country are returned.

In the case that the file reading of etfs.csv or the retrieval process from Investing.com was successfully completed, the resulting pandas.DataFrame will look like:

country | name | full_name | symbol | isin | asset_class | currency | stock_exchange | def_stock_exchange
--------|------|-----------|--------|------|-------------|----------|----------------|--------------------
xxxxxxx | xxxx | xxxxxxxxx | xxxxxx | xxxx | xxxxxxxxxxx | xxxxxxxx | xxxxxxxxxxxxxx | xxxxxxxxxxxxxxxxxx

Return type

pandas.DataFrame - etfs

Raises

  • ValueError – raised when any of the input arguments is not valid.

  • FileNotFoundError – raised when etfs.csv file was not found.

  • IOError – raised when etfs.csv file is missing.

investpy.etfs.get_etfs_dict(country=None, columns=None, as_json=False)

This function retrieves all the available etfs indexed on Investing.com, already stored on etfs.csv. This function also allows the user to specify which country do they want to retrieve data from, or from every listed country; the columns which the user wants to be included on the resulting dict; and the output of the function will either be a dict or a json.

Parameters

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

  • columns (list, optional) – names of the columns of the etf data to retrieve <country, name, full_name, symbol, isin, asset_class, currency, stock_exchange>

  • as_json (bool, optional) – value to determine the format of the output data which can either be a dict or a json.

Returns

The resulting dict contains the retrieved data if found, if not, the corresponding fields are filled with None values.

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

etfs_dict = {
    "country": country,
    "name": name,
    "full_name": full_name,
    "symbol": symbol,
    "isin": isin,
    "asset_class": asset_class,
    "currency": currency,
    "stock_exchange": stock_exchange,
    "def_stock_exchange": def_stock_exchange
}

Return type

dict or json - etfs_dict

Raises

  • ValueError – raised when any of the input arguments is not valid.

  • FileNotFoundError – raised when etfs.csv file was not found.

  • IOError – raised when etfs.csv file is missing.

investpy.etfs.get_etfs_list(country=None)

This function retrieves all the available etfs indexed on Investing.com, already stored on etfs.csv. This function also allows the users to specify which country do they want to retrieve data from or if they want to retrieve it from every listed country; so on, a listing of etfs will be returned. This function helps the user to get to know which etfs are available on Investing.com.

Parameters

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

Returns

The resulting list contains the retrieved data from the etfs.csv file, which is a listing of the names of the etfs listed on Investing.com, which is the input for data retrieval functions as the name of the etf to retrieve data from needs to be specified.

In case the listing was successfully retrieved, the list will look like:

etfs_list = [
    'Betashares U.S. Equities Strong Bear Currency Hedg',
    'Betashares Active Australian Hybrids',
    'Australian High Interest Cash', ...
]

Return type

list - etfs_list

Raises

  • ValueError – raised when any of the input arguments is not valid.

  • FileNotFoundError – raised when etfs.csv file was not found.

  • IOError – raised when etfs.csv file is missing.

investpy.etfs.get_etfs_overview(country, as_json=False, n_results=100)

This function retrieves an overview containing all the real time data available for the main ETFs from a country, such as the ETF 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 main ETFs from a country, so to get a general view. Note that since this function is retrieving a lot of information at once, by default just the overview of the Top 100 ETFs is being retrieved, but an additional parameter called n_results can be specified so to retrieve N results.

Parameters

  • country (str) – name of the country to retrieve the ETFs overview from.

  • as_json (bool, optional) – optional argument to determine the format of the output data (pandas.DataFrame or json).

  • n_results (int, optional) – number of results to be displayed on the overview table (0-1000).

Returns

The resulting pandas.DataFrame contains all the data available in Investing.com of the main ETFs 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 | full_name | symbol | last | change | turnover
--------|------|-----------|--------|------|--------|----------
xxxxxxx | xxxx | xxxxxxxxx | xxxxxx | xxxx | xxxxxx | xxxxxxxx

Return type

pandas.DataFrame - etfs_overview

Raises

  • ValueError – raised if there was any argument error.

  • FileNotFoundError – raised when etfs.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.etfs.search_etfs(by, value)

This function searches etfs 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 value for the specified field which is the etfs.csv column name to search in. Available fields to search etfs are ‘name’, ‘full_name’ and ‘symbol’.

Parameters

  • by (str) – name of the field to search for, which is the column name (‘name’, ‘full_name’ or ‘symbol’).

  • value (str) – value of the field to search for, which is the str that is going to be searched.

Returns

The resulting pandas.DataFrame contains the search results from the given query (the specified value in the specified field). If there are no results and error will be raised, but otherwise this pandas.DataFrame will contain all the available field values that match the introduced query.

Return type

pandas.DataFrame - search_result

Raises

  • ValueError – raised if any of the introduced params is not valid or errored.

  • FileNotFoundError – raised if etfs.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.