Welcome to financialdatapy’s documentation!¶
financialdatapy is a package for getting a fundamental financial data of a company. Currently it supports financial data of companies listed in United States (NASDAQ, NYSE) and South Korea (KOSPI, KOSDAQ).
User can see the company’s latest financial statement reported, standard financials, and historical stock price. financialdatapy will be a good choice for research purposes, and managing an investment portfolio.
Installation¶
To use financialdatapy, first install it using pip:
Note
Python version above 3.10 is required to use financialdatapy.
pip install financialdatapy
Quick Start¶
financialdatapy supports three major financial statements of a company. Income statement, balance sheet, and cash flow. Also the user can select between annual and quarter financial statements.
Checkout the usage in Usage page, and notebook
API Key¶
❗️When getting financial statements of a company listed in Korea stock exchange, API Key from DART should be provided in the system to successfully retrieve its data.
After receiving API key, store it on a .env file in the root directory of your project.
Inside .env file, provide api key as shown below.
DART_API_KEY=xxxxxxxxxxxxxxxx
SEC User-Agent¶
❗️When getting data of a company listed in US stock exchange, SEC
requires every request to declare who is sending it. Requests without it are rejected with 403 Forbidden.
Store your own name and email on the same .env file, in the format SEC asks for.
Inside .env file.
SEC_USER_AGENT=App Name your@email.com
If it is not set, financialdatapy.exception.EmptySecUserAgentException is raised before the request is sent.
Browser User-Agent¶
❗️`investing.com <https://www.investing.com/>`_, the data source for KOR stock price, rejects requests that do not
come from a current browser. Declare your own browser’s User-Agent to retrieve its data. If it is not set, a
randomized User-Agent is sent instead, which investing.com refuses with 403 Forbidden.
You can find your browser’s User-Agent by opening
whatismybrowser.com, or by running
navigator.userAgent in your browser’s developer console.
Inside .env file.
USER_AGENT=xxxxxxxxxxxxxxxx
Initialization¶
from financialdatapy.stock import Stock
# Apple
us_comp = Stock('aapl')
# Samsung Electronics
kor_comp = Stock('005930', country_code='kor') # should specify 'country_code' for stock exchange other than USA
Values passed for financial statements and periods should follow the format below. If no argument is passed, it automatically retrieves income statement from annual report.
income_statement = us_comp.financials('income_statement')
balance_sheet = us_comp.financials('balance_sheet')
cash_flow = us_comp.financials('cash_flow')
# Annual Report
income_statement = kor_comp.financials('income_statement', 'annual')
# Quarterly Report
income_statement = kor_comp.financials('income_statement', 'quarter')
Financial Statement as reported¶
Financial statements reported by the company to a financial regulator.
The elements in the financial statements are different from others, depending on the comapany and stock exchange.
United States Stock Exchange
us_comp = Stock('aapl')
ic_as_reported = us_comp.financials('income_statement', 'annual')
Korea Stock Exchange
kor_comp = Stock('005930', country_code='kor') # should specify 'country_code' for stock exchange other than USA
ic_as_reported = kor_comp.financials('income_statement', 'annual')
To see the full financial report from a browser, pass True in web. Supports both US exchange and KOR exchange.
us_comp.financials(web=True)
kor_comp.financials(web=True)
Standard Financial Statement¶
Warning
Currently getting standard financial statements is not available. The investing.com endpoint it depends on
responds with 403 Forbidden even to a current browser User-Agent, so setting USER_AGENT does not
restore it.
Summarized financial statements of a company.
us_comp = Stock('aapl')
std_ic = us_comp.financials('income_statement', 'annual', is_standard=True)
Historical Stock Data¶
Important
Getting historical data of stocks listed in KOR exchange requires USER_AGENT to be set. See the
Browser User-Agent section above. Without it the request is rejected with 403 Forbidden and
price() raises requests.exceptions.HTTPError.
US exchange is unaffected.
Historical stock price of the company.
us_comp = Stock('aapl')
price = us_comp.price('2021-1-1', '2021-1-5')
All of the above will return in pandas.DataFrame.
Note
Data source of stock price data differ from US stock exchange to KOR stock exchange.
Exchange |
Source |
|---|---|
USA |
|
KOR |
Contribute¶
It will be a great help if you contribute to the package. You can open issues here!
Code style¶
The project basically follows PEP-8, Google Python Style Guide.
Git commit messages¶
The project basically follows Conventional Commits. Click on the badge to see the details.
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
Documentation¶
The documentation is built with Sphinx and deployed with Read the Docs.
License¶
Licensed under the MIT License
Disclaimer¶
financialdatapy is not meant to be used in any kind of trading. The data might not be accurate, and timely.
financialdatapy is aimed for people who use stock data in their portfolio management and researchers who need stock
market data in their research. So if you are willing to use data for trading, there are lot more better options.