`investpy.commodities`¶

investpy.commodities.get_commodities(group=None)¶

This function retrieves all the commodities data stored in commodities.csv file, which previously was retrieved from Investing.com. Since the resulting object is a matrix of data, the commodities data is properly structured in rows and columns, where columns are the commodity data attribute names. Additionally, group filtering can be specified, so that the return commodities are from the specified group instead from every available group. Anyways, since it is an optional parameter it does not need to be specified, which means that if it is None or not specified, all the available commodities will be returned.

Parameters

group (str, optional) – name of the group to retrieve all the available commodities from.

Returns

The resulting pandas.DataFrame contains all the commodities data from the introduced group if specified, or from all the commodity groups 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:

title | country | name | full_name | currency | group
------|---------|------|-----------|----------|-------
xxxxx | xxxxxxx | xxxx | xxxxxxxxx | xxxxxxxx | xxxxx

Return type

pandas.DataFrame - commodities_df

Raises

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

investpy.commodities.get_commodities_dict(group=None, columns=None, as_json=False)¶

This function retrieves all the commodities information stored in the commodities.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 group, columns or as_json, which are the name of the commodity group to filter between all the available commodities so not to return all the commodities but just the ones from the introduced group, 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

group (str, optional) – name of the group to retrieve all the available commodities from.
columns (list, optional) – column names of the commodities data to retrieve, can be: <title, country, name, full_name, currency, group>
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:

commodities_dict = {
    'title': title,
    'country': country,
    'name': name,
    'full_name': full_name,
    'currency': currency,
    'group': group,
}

Return type

list of dict OR json - bonds_dict

Raises

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

investpy.commodities.get_commodities_list(group=None)¶

This function retrieves all the commodity names as stored in commodities.csv file, which contains all the data from the commodities as previously retrieved from Investing.com. So on, this function will just return the commodity names from either all the available groups or from any group, which will later be used when it comes to both recent and historical data retrieval.

Parameters

group (str, optional) – name of the group to retrieve all the available commodities from.

Returns

The resulting list contains the all the commodity names from the introduced group if specified, or from every group 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 commodity names will look like:

commodities_list = ['Gold', 'Copper', 'Silver', 'Palladium', 'Platinum', ...]

Return type

list - commodities_list

Raises

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

investpy.commodities.get_commodities_overview(group, as_json=False, n_results=100)¶

This function retrieves an overview containing all the real time data available for the main commodities from every commodity group (metals, softs, meats, energy and grains), 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 main commodities from a group, 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 commodities is being retrieved, but an additional parameter called n_results can be specified so to retrieve N results. Anyways, note that in commodities case, there are just a few ones available.

Parameters

group (str) – name of the commodity group to retrieve an 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 commodities from a commodity group 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 | currency
--------|------|------|------------|------|-----|--------|-------------------|----------
xxxxxxx | xxxx | xxxx | xxxxxxxxxx | xxxx | xxx | xxxxxx | xxxxxxxxxxxxxxxxx | xxxxxxxx

Return type

pandas.DataFrame - commodities_overview

Raises

ValueError – raised if any of the introduced arguments errored.
FileNotFoundError – raised if commodities.csv file is missing.
IOError – raised if data could not be retrieved due to file error.
RuntimeError – raised either if the introduced group 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.commodities.get_commodity_groups()¶

This function returns a listing with all the available commodity groupsson that a filtering can be applied when retrieving data from commodities. The current available commodity groups are metals, agriculture and energy, which include all the raw materials or commodities included in them.

Returns

The resulting list contains all the available commodity groups as indexed in Investing.com

Return type

list - commodity_groups

Raises

FileNotFoundError – raised when commodities.csv file was not found.
IOError – raised when commodities.csv file is missing or empty.

investpy.commodities.get_commodity_historical_data(commodity, from_date, to_date, country=None, as_json=False, order='ascending', interval='Daily')¶

This function retrieves historical data from the introduced commodity from Investing.com. So on, the historical data of the introduced commodity 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

commodity (str) – name of the commodity to retrieve recent 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.
country (str, optional) – name of the country to retrieve the commodity data from (if there is more than one country that provides data from the same commodity).
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 historical data of the specified commodity. So on, the resulting dataframe contains the open, high, low and close values for the selected commodity on market days and the currency in which those values are presented.

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

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

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,
            volume: x,
            currency: x
        },
        ...
    ]
}

Return type

pandas.DataFrame or json

Raises

ValueError – raised whenever any of the introduced arguments is not valid or errored.
IOError – raised if commodities object/file was not found or unable to retrieve.
RuntimeError – raised if the introduced commodity 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 commodity historical data was unavailable or not found in Investing.com.

Examples

>>> data = investpy.get_commodity_historical_data(commodity='gold', from_date='01/01/2018', to_date='01/01/2019')
>>> data.head()
              Open    High     Low   Close  Volume Currency
Date
2018-01-01  1305.8  1309.7  1304.6  1308.7       0      USD
2018-01-02  1370.5  1370.5  1370.5  1370.5      97      USD
2018-01-03  1372.0  1372.0  1369.0  1374.2      22      USD
2018-01-04  1363.4  1375.6  1362.7  1377.4      13      USD
2018-01-05  1377.8  1377.8  1377.8  1378.4      10      USD

investpy.commodities.get_commodity_information(commodity, country=None, as_json=False)¶

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

Parameters

commodity (str) – name of the commodity to retrieve information from.
country (str, optional) – name of the country to retrieve the commodity information from (if there is more than one country that provides data from the same commodity).
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 commodity; 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:

commodity_information = {
    "1-Year Change": "16.15%",
    "52 wk Range": "1,270.2 - 1,566.2",
    "Base Symbol": "GC",
    "Commodity Name": "Gold",
    "Contract Size": "100 Troy Ounces",
    "Last Rollover Day": "24/11/2019",
    "Month": "Feb 20",
    "Months": "GJMQVZ",
    "Open": 1479.8,
    "Point Value": "$100",
    "Prev. Close": 1481.2,
    "Settlement Day": "25/01/2020",
    "Settlement Type": "Physical",
    "Tick Size": 0.1,
    "Tick Value": 10.0,
    "Day's Range": "1,477.55 - 1,484.25"
}

Return type

pandas.DataFrame or dict- commodity_information

Raises

ValueError – raised if any of the introduced arguments is not valid or errored.
FileNotFoundError – raised if commodities.csv file was not found or errored.
IOError – raised if commodities.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.commodities.get_commodity_recent_data(commodity, country=None, as_json=False, order='ascending', interval='Daily')¶

This function retrieves recent historical data from the introduced commodity from Investing.com, which will be 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

commodity (str) – name of the commodity to retrieve recent data from.
country (str, optional) – name of the country to retrieve the commodity data from (if there is more than one country that provides data from the same commodity).
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 commodity. So on, the resulting dataframe contains the open, high, low and close values for the selected commodity on market days and the currency in which those values are presented.

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

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

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,
            volume: x,
            currency: x
        },
        ...
    ]
}

Return type

pandas.DataFrame or json

Raises

ValueError – raised whenever any of the introduced arguments is not valid or errored.
IOError – raised if commodities object/file was not found or unable to retrieve.
RuntimeError – raised if the introduced commodity 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 commodity recent data was unavailable or not found in Investing.com.

Examples

>>> data = investpy.get_commodity_recent_data(commodity='gold')
>>> data.head()
              Open    High     Low   Close  Volume Currency
Date
2019-10-25  1506.4  1520.9  1503.1  1505.3  368743      USD
2019-10-28  1507.4  1510.8  1492.3  1495.8  318126      USD
2019-10-29  1494.3  1497.1  1485.6  1490.7  291980      USD
2019-10-30  1490.5  1499.3  1483.1  1496.7  353638      USD
2019-10-31  1498.8  1516.7  1496.0  1514.8  390013      USD

investpy.commodities.search_commodities(by, value)¶

This function searches commodities 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 commodities.csv column name to search in. Available fields to search commodities are ‘name’, ‘full_name’ and ‘title’.

Parameters

by (str) – name of the field to search for, which is the column name which can be: ‘’name’, ‘full_name’ or ‘title’.
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 commodities 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 commodities.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.commodities¶

`investpy.commodities`¶