investpy.stocks
ΒΆ
-
investpy.stocks.
get_stock_company_profile
(stock, country='spain', language='english')ΒΆ This function retrieves the company profile of a stock company in the specified language. This function is really useful if NLP techniques want to be applied to stocks, since the company profile is a short description of what the company does and since it is written by the company, it can give the user an overview on what does the company do. The company profile can be retrieved either in english or in spanish, the only thing that changes is the source from where the data is retrieved, but the resulting object will be the same. Note that this functionalliy as described in the docs is just supported for spanish stocks currently, so on, if any other stock from any other country is introduced as parameter, the function will raise an exception.
Note
Currently just the spanish company profile can be retrieved from spanish stocks, so if you try to retrieve it in spanish for any other country, this function will raise a ValueError exception.
- Parameters
stock (
str
) β symbol of the stock to retrieve its company profile from.country (
str
) β name of the country from where the stock is.language (
str
, optional) β language in which the company profile is going to be retrieved, can either be english or spanish.
- Returns
The resulting
dict
contains the retrieved company profile from the selected source depending on the specified language in the function parameters, which can be either Investing.com (english) or Bolsa de Madrid (spanish); and the URL from where it was retrieved, so to have both the source and the description of the company_profile.So the resulting
dict
should look like:company_profile = { url: 'https://www.investing.com/equities/bbva-company-profile', desc: 'Banco Bilbao Vizcaya Argentaria, S.A. (BBVA) is a ...' }
- Return type
dict
- company_profile- Raises
ValueError β raised whenever any of the introduced arguments is not valid or errored.
FileNotFound β raised if the stocks.csv file was not found or unable to retrieve.
IOError β raised if stocks object/file was not found or unable to retrieve.
RuntimeError β raised if the introduced stock/country was not found or did not match any of the existing ones.
ConnectionError β raised if connection to Investing.com could not be established.
Examples
>>> company_profile = investpy.get_stock_company_profile(stock='bbva', country='spain', language='english') >>> company_profile company_profile = { url: 'https://www.investing.com/equities/bbva-company-profile', desc: 'Banco Bilbao Vizcaya Argentaria, S.A. (BBVA) is a ...' }
-
investpy.stocks.
get_stock_countries
()ΒΆ This function returns a listing with all the available countries from where stocks can be retrieved, so to let the user know which of them are available, since the parameter country is mandatory in every stock retrieval function.
- Returns
The resulting
list
contains all the available countries with stocks as indexed in Investing.com- Return type
list
- countries
-
investpy.stocks.
get_stock_dividends
(stock, country)ΒΆ This function retrieves the stock dividends from the introduced stocks, which are token rewards paid to the shareholders for their investment in a companyβs stock/equity. Dividends data include date of the dividend, dividend value, type, payment date and yield. This information is really useful when it comes to creating portfolios.
- Parameters
stock (
str
) β symbol of the stock to retrieve its dividends from.country (
country
) β name of the country from where the stock is from.
- Returns
Returns a
pandas.DataFrame
containing the retrieved information of stock dividends for every stock symbol introduced as parameter.So on, the resulting
pandas.DataFrame
will look like:Date Dividend Type Payment Date Yield 0 2019-10-11 0.2600 trailing_twelve_months 2019-10-15 5,67% 1 2019-04-08 0.2600 trailing_twelve_months 2019-04-10 5,53% 2 2018-06-11 0.3839 trailing_twelve_months 2018-06-13 3,96% 3 2018-04-06 0.2400 trailing_twelve_months 2018-04-10 4,41% 4 2017-10-06 0.3786 trailing_twelve_months 2017-10-10 4,45%
- Return type
pandas.DataFrame
- stock_dividends
-
investpy.stocks.
get_stock_financial_summary
(stock, country, summary_type='income_statement', period='annual')ΒΆ This function retrieves the financial summary of the introduced stock (by symbol) from the introduced country, based on the summary_type value this function returns a different type of financial summary, so that the output format of this function depends on its type. Additionally, the period of the retrieved financial summary type can be specified.
- Parameters
stock (
str
) β symbol of the stock to retrieve its financial summary.country (
str
) β name of the country from where the introduced stock symbol is.summary_type (
str
, optional) β type of the financial summary table to retrieve, default value is income_statement, but all the available types are: income_statement, cash_flow_statement and balance_sheet.period (
str
, optional) β period range of the financial summary table to rertieve, detault value is annual, but all the available periods are: annual and quarterly.
- Returns
The resulting
pandas.DataFrame
contains the table of the requested financial summary from the introduced stock, so the fields/column names may vary, since it depends on the summary_type introduced. So on, the returned table will have the following format/structure:Date || Field 1 | Field 2 | ... | Field N -----||---------|---------|-----|--------- xxxx || xxxxxxx | xxxxxxx | xxx | xxxxxxx
- Return type
pandas.DataFrame
- financial_summary- Raises
ValueError β raised if any of the introduced parameters is not valid or errored.
FileNotFoundError β raised if the stocks.csv file was not found.
IOError β raised if the stocks.csv file could not be read.
ConnectionError β raised if the connection to Investing.com errored or could not be established.
RuntimeError β raised if any error occurred while running the function.
Examples
>>> data = investpy.get_stock_financial_summary(stock='AAPL', country='United States', summary_type='income_statement', period='annual') >>> data.head() Total Revenue Gross Profit Operating Income Net Income Date 2019-09-28 260174 98392 63930 55256 2018-09-29 265595 101839 70898 59531 2017-09-30 229234 88186 61344 48351 2016-09-24 215639 84263 60024 45687
-
investpy.stocks.
get_stock_historical_data
(stock, country, from_date, to_date, as_json=False, order='ascending', interval='Daily')ΒΆ This function retrieves historical data from the introduced stock from Investing.com. So on, the historical data of the introduced stock from the specified country 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 ajson
or not, and if the historical data is going to be ordered ascending or descending (where the index is the date), respectively.- Parameters
stock (
str
) β symbol of the stock to retrieve historical data from.country (
str
) β name of the country from where the stock is.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 apandas.DataFrame
if False and ajson
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 ajson
object, containing the retrieved historical data of the specified stock from the specified country. So on, the resulting dataframe contains the open, high, low, close and volume values for the selected stock 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 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 }, ... ] }
- Return type
pandas.DataFrame
orjson
- Raises
ValueError β raised whenever any of the introduced arguments is not valid or errored.
IOError β raised if stocks object/file was not found or unable to retrieve.
RuntimeError β raised if the introduced stock/country 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 stock historical data was unavailable or not found in Investing.com.
Examples
>>> data = investpy.get_stock_historical_data(stock='bbva', country='spain', from_date='01/01/2010', to_date='01/01/2019') >>> data.head() Open High Low Close Volume Currency Date 2010-01-04 12.73 12.96 12.73 12.96 0 EUR 2010-01-05 13.00 13.11 12.97 13.09 0 EUR 2010-01-06 13.03 13.17 13.02 13.12 0 EUR 2010-01-07 13.02 13.11 12.93 13.05 0 EUR 2010-01-08 13.12 13.22 13.04 13.18 0 EUR
-
investpy.stocks.
get_stock_information
(stock, country, as_json=False)ΒΆ This function retrieves fundamental financial information from the specified stock. The retrieved information from the stock 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 stock.
- Parameters
stock (
str
) β symbol of the stock to retrieve its information from.country (
country
) β name of the country from where the stock is from.as_json (
bool
, optional) β optional argument to determine the format of the output data (dict
orjson
).
- Returns
The resulting
pandas.DataFrame
contains the information fields retrieved from Investing.com from the specified stock ; it can also be returned as adict
, 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:stock_information = { "Stock Symbol": "AAPL", "Prev. Close": 267.25, "Todays Range": "263.45 - 268.25", "Revenue": 260170000000.00003, "Open": 267.27, "52 wk Range": "142 - 268.25", "EPS": 11.85, "Volume": 23693550.0, "Market Cap": 1173730000000.0, "Dividend (Yield)": "3.08 (1.15%)", "Average Vol. (3m)": 25609925.0, "P/E Ratio": 22.29, "Beta": 1.23, "1-Year Change": "47.92%", "Shares Outstanding": 4443236000.0, "Next Earnings Date": "04/02/2020" }
- Return type
pandas.DataFrame
ordict
- stock_information- Raises
ValueError β raised if any of the introduced arguments is not valid or errored.
FileNotFoundError β raised if stocks.csv file was not found or errored.
IOError β raised if stocks.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.stocks.
get_stock_recent_data
(stock, country, as_json=False, order='ascending', interval='Daily')ΒΆ This function retrieves recent historical data from the introduced stock from Investing.com. So on, the recent data of the introduced stock from the specified country 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 ajson
or not, and if the historical data is going to be ordered ascending or descending (where the index is the date), respectively.- Parameters
stock (
str
) β symbol of the stock to retrieve recent historical data from.country (
str
) β name of the country from where the stock is.as_json (
bool
, optional) β to determine the format of the output data, either apandas.DataFrame
if False and ajson
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 ajson
object, containing the retrieved recent data of the specified stock from the specified country. So on, the resulting dataframe contains the open, high, low, close and volume values for the selected stock on market days and the currency in which those values are presented.The resulting recent data, in case that the default parameters were applied, 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
orjson
- Raises
ValueError β raised whenever any of the introduced arguments is not valid or errored.
IOError β raised if stocks object/file was not found or unable to retrieve.
RuntimeError β raised if the introduced stock/country 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 stock recent data was unavailable or not found in Investing.com.
Examples
>>> data = investpy.get_stock_recent_data(stock='bbva', country='spain') >>> data.head() Open High Low Close Volume Currency Date 2019-08-13 4.263 4.395 4.230 4.353 27250000 EUR 2019-08-14 4.322 4.325 4.215 4.244 36890000 EUR 2019-08-15 4.281 4.298 4.187 4.234 21340000 EUR 2019-08-16 4.234 4.375 4.208 4.365 46080000 EUR 2019-08-19 4.396 4.425 4.269 4.269 18950000 EUR
-
investpy.stocks.
get_stocks
(country=None)ΒΆ This function retrieves all the stock data stored in stocks.csv file, which previously was retrieved from Investing.com. Since the resulting object is a matrix of data, the stock data is properly structured in rows and columns, where columns are the stock data attribute names. Additionally, country filtering can be specified, which will make this function return not all the stored stock data, but just the stock data of the stocks from the introduced country.
- Parameters
country (
str
, optional) β name of the country to retrieve all its available stocks from.- Returns
The resulting
pandas.DataFrame
contains all the stock 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 | isin | currency | symbol --------|------|-----------|------|----------|-------- xxxxxxx | xxxx | xxxxxxxxx | xxxx | xxxxxxxx | xxxxxx
- Return type
pandas.DataFrame
- stocks_df- Raises
ValueError β raised whenever any of the introduced arguments is not valid.
FileNotFoundError β raised if stocks.csv file was not found.
IOError β raised when stocks.csv file is missing or empty.
-
investpy.stocks.
get_stocks_dict
(country=None, columns=None, as_json=False)ΒΆ This function retrieves all the stock information stored in the stocks.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 alist
. 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 stocks 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 stocks from.columns (
list
, optional) β column names of the stock data to retrieve, can be: <country, name, full_name, isin, currency, symbol>as_json (
bool
, optional) β if True the returned data will be ajson
object, if False, alist
ofdict
.
- Returns
The resulting
list
ofdict
contains the retrieved data from every stock 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
ofdict
will look like:stocks_dict = { 'country': country, 'name': name, 'full_name': full_name, 'isin': isin, 'currency': currency, 'symbol': symbol, }
- Return type
list
ofdict
ORjson
- stocks_dict- Raises
ValueError β raised whenever any of the introduced arguments is not valid.
FileNotFoundError β raised if stocks.csv file was not found.
IOError β raised when stocks.csv file is missing or empty.
-
investpy.stocks.
get_stocks_list
(country=None)ΒΆ This function retrieves all the stock symbols stored in stocks.csv file, which contains all the data from the stocks as previously retrieved from Investing.com. So on, this function will just return the stock symbols which will be one of the input parameters when it comes to stock data retrieval functions from investpy. Additionally, note that the country filtering can be applied, which is really useful since this function just returns the symbols and in stock data retrieval functions both the symbol and the country must be specified and they must match.
- Parameters
country (
str
, optional) β name of the country to retrieve all its available stocks from.- Returns
The resulting
list
contains the all the stock symbols 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 stock symbols will look like:stocks_list = ['TS', 'APBR', 'GGAL', 'TXAR', 'PAMP', ...]
- Return type
list
- stocks_list- Raises
ValueError β raised whenever any of the introduced arguments is not valid.
FileNotFoundError β raised if stocks.csv file was not found.
IOError β raised when stocks.csv file is missing or empty.
-
investpy.stocks.
get_stocks_overview
(country, as_json=False, n_results=100)ΒΆ This function retrieves an overview containing all the real time data available for the main stocks 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 main stocks 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 stocks 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 stocks overview from.as_json (
bool
, optional) β optional argument to determine the format of the output data (pandas.DataFrame
orjson
).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 stocks 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 | symbol | last | high | low | change | change_percentage | turnover | currency --------|------|--------|------|------|-----|--------|-------------------|----------|---------- xxxxxxx | xxxx | xxxxxx | xxxx | xxxx | xxx | xxxxxx | xxxxxxxxxxxxxxxxx | xxxxxxxx | xxxxxxxx
- Return type
pandas.DataFrame
- stocks_overview- Raises
ValueError β raised if any of the introduced arguments errored.
FileNotFoundError β raised when stocks.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.stocks.
search_stocks
(by, value)ΒΆ This function searches stocks 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 stocks.csv column name to search in. Available fields to search stocks are βnameβ, βfull_nameβ and βisinβ.
- Parameters
by (
str
) β name of the field to search for, which is the column name which can be: βnameβ, βfull_nameβ or βisinβ.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 resultingpandas.DataFrame
will contain all the available stocks 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 stocks.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.