equities aims to democratize access to public company data.
Project description
🐋 equities
Democratizing Access to U.S. Public Company Data
Overview:
equities is an intuitive package for accessing high fidelity public company financial data.
equities takes the approach of composing already existing stable and highly maintained libraries and apis.
All data is served back to the user as dictionary objects or pandas dataframes.
Data Sources:
Financial Statements:
Sec Xbrl Financial Statement Data:
- https://www.sec.gov/dera/data/financial-statement-data-sets.html
Prices, Recommendations, Major Holders, etc:
Yfinance Pypi Package
- https://pypi.org/project/yfinance/
Trend Data
pytrends Pypi Package
- https://pypi.org/project/pytrends/
Install:
pip3 install equities
TUTORIAL:
Instantiating a Universe
We begin by initializing a universe client.
from equities import Universe
u = Universe(verbose=True)
The verbose optional argument defaults to False. The results of initializing with the verbose=True looks something like this:
----------------------------------------
🐋 Welcome to equities.
----------------------------------------
Initializing Universe...
> ✨ Auth success. apis connected.
> 🌌 Universe initialized. size: 7896
Success. You're good to go!
----------------------------------------
Essential Methods
To get the number of companies in the universe call:
len(u)
"CIK" numbers are the sec's official unique identifier for public companies. It stands for "Central Index Key" A full list of the cik numbers in the universe is found in:
u.ciks
Similarly, if we want the names of companies in the universe we can call:
u.names
Finally, to get tickers we call:
u.tickers
To get a dictionary mapping "cik" numbers to the names of companies execute:
u.cik_to_name()
We can get get a map of cik numbers to tickers through :
u.cik_to_ticker()
The inverses of both of these dictionaries are also accessible through u.name_to_cik() and u.ticker_to_cik()
Search:
You can search for companies by names, ticker or ciks by using the search function. Note that in all universe queries handle for case and whitespace.
u.search("netflix")
Here are the results of this query.
> 🛰️ Search query: "netflix" found 1 matches.
{'NETFLIX INC': '1065280'}
Let's find the ticker of this company.
u.cik_to_ticker()['1065280']
Here are results:
'nflx'
Queries:
Company
company data can be obtained by passing a "cik" or "ticker" into the "company()" function on the universe.
u.company('nflx')
# we can also pass in a query like this: u.company("Netflix",search=True).
# It returns the first result of the search query.
The above requests returns a dictionary. Here are it's keys:
dict_keys(
['name',
'sic',
'business_address',
'mailing_address',
'phone',
'country_incorporated',
'state_incorporated', 'ein',
'former_name',
'income',
'balance',
'cash',
'equity',
'prices',
'actions',
'dividends',
'splits',
'major_holders',
'institutional_holders',
'events',
'recommendations',
'esg']
)
Now see below the full response from the request.
Observe that the keys, "income","balance","cash","equity" are dataframes and encode the income statement, balance sheet, cashflow statement and equity statement respectively of the company in question. Other keys also map to dataframes for example "prices" and "institutional holders". Naming conventions and structure is chosen for simplicity.
> 📦 Fetching company: 1065280 ...
{
"name " : " NETFLIX INC ",
"sic " : " 7841.0 ",
"business_address " :
{
'country': 'US',
'city': 'LOS GATOS',
'zip': '95032',
'adr1': '100 WINCHESTER CIRCLE',
'adr2': '.'
},
"mailing_address " :
{
'country': 'US',
'city': 'LOS GATOS',
'zip': '95032-7606',
'adr1': '100 WINCHESTER CIRCLE',
'adr2': 'nan',
'state': 'CA'
},
"phone " : "408-540-3700 ",
"country_incorporated " : " US ",
"state_incorporated " : " DE ",
"ein " : " 770467272.0 ",
"former_name " : " NETFLIX COM INC ",
"income " : 2009q2 2009q3 2009q4 2010q1 2010q2 ... 2019q2 2019q3 2019q4 2020q2 2020q3
Revenues None None None None None ... 3.700856e+09 3.907270e+09 3.999374e+09 5.767691e+09 6.148286e+09
CostOfRevenue None None None None None ... 2.300579e+09 5.876271e+09 8.974190e+09 2.870614e+09 3.643707e+09
MarketingExpense None None None None None ... 6.165780e+08 5.920070e+08 5.103300e+08 5.038300e+08 1.219728e+09
ResearchAndDevelopmentExpense None None None None None ... 2.823100e+08 5.814050e+08 8.900250e+08 4.538170e+08 3.832330e+08
GeneralAndAdministrativeExpense None None None None None ... 2.019520e+08 1.515240e+08 1.686280e+08 2.520870e+08 2.246570e+08
OperatingIncomeLoss None None None None None ... 4.465780e+08 4.622130e+08 4.806680e+08 4.590840e+08 7.064190e+08
InterestExpense None None None None None ... 1.355290e+08 2.875620e+08 4.482220e+08 1.355290e+08 1.891510e+08
NonoperatingIncomeExpense None None None None None ... 7.610400e+07 6.802800e+07 7.004000e+06 2.169700e+07 2.263400e+07
IncomeLossFromContinuingOperationsBeforeIncomeT... None None None None None ... 3.996590e+08 7.282520e+08 1.107062e+09 7.958700e+08 9.005750e+08
IncomeTaxExpenseBenefit None None None None None ... 9.492000e+06 4.428700e+07 6.329520e+08 8.680300e+07 3.154060e+08
NetIncomeLoss None None None None None ... 2.901240e+08 3.843490e+08 4.028350e+08 3.440520e+08 2.706500e+08
EarningsPerShareBasic None None None None None ... 7.900000e-01 8.800000e-01 9.200000e-01 7.900000e-01 6.200000e-01
EarningsPerShareDiluted None None None None None ... 7.600000e-01 1.360000e+00 2.830000e+00 7.600000e-01 1.360000e+00
WeightedAverageNumberOfSharesOutstandingBasic None None None None None ... 4.341740e+08 4.375870e+08 4.380900e+08 4.369470e+08 4.375870e+08
WeightedAverageNumberOfDilutedSharesOutstanding None None None None None ... 4.503590e+08 4.520630e+08 4.518960e+08 4.519220e+08 4.520630e+08
GainsLossesOnExtinguishmentOfDebt None None None None None ... NaN NaN NaN NaN NaN
OtherNonoperatingIncome None None None None None ... NaN NaN NaN NaN NaN
CostOfGoodsSoldSubscription None None None None None ... NaN NaN NaN NaN NaN
FulfillmentExpense None None None None None ... NaN NaN NaN NaN NaN
GrossProfit None None None None None ... NaN NaN NaN NaN NaN
OperatingExpenses None None None None None ... NaN NaN NaN NaN NaN
TechnologyandDevelopmentExpense None None None None None ... NaN NaN NaN NaN NaN
[22 rows x 44 columns] ,
"balance " : 2009q2 2009q3 2009q4 2010q1 2010q2 ... 2019q2 2019q3 2019q4 2020q2 2020q3
CommonStockParOrStatedValuePerShare None None None None None ... 1.000000e-03 1.000000e-03 1.000000e-03 1.000000e-03 1.000000e-03
CommonStockSharesAuthorized None None None None None ... 4.990000e+09 4.990000e+09 4.990000e+09 4.990000e+09 4.990000e+09
CommonStockSharesIssued None None None None None ... 4.365986e+08 4.378349e+08 4.382513e+08 4.397806e+08 4.410154e+08
CashAndCashEquivalentsAtCarryingValue None None None None None ... 3.794483e+09 3.794483e+09 3.794483e+09 5.151884e+09 7.153248e+09
AvailableForSaleSecuritiesCurrent None None None None None ... NaN NaN NaN NaN NaN
CommonStockSharesOutstanding None None None None None ... 4.365986e+08 4.365986e+08 4.382513e+08 4.397806e+08 4.388066e+08
ContentAssetsNetCurrent None None None None None ... NaN NaN NaN NaN NaN
OtherAssetsCurrent None None None None None ... 8.203500e+08 7.484660e+08 7.484660e+08 1.295897e+09 1.160067e+09
AssetsCurrent None None None None None ... 9.694135e+09 9.694135e+09 9.694135e+09 6.178504e+09 8.564139e+09
ContentAssetsNetNoncurrent None None None None None ... 2.088878e+10 NaN 2.323499e+10 2.526689e+10 2.515512e+10
PropertyPlantAndEquipmentNet None None None None None ... 4.343720e+08 4.182810e+08 4.819920e+08 5.652210e+08 7.519410e+08
OtherAssetsNoncurrent None None None None None ... 1.726568e+09 1.896043e+09 9.010300e+08 2.727420e+09 2.727420e+09
Assets None None None None None ... 2.721863e+10 3.017134e+10 3.094171e+10 3.505991e+10 3.717528e+10
ContentLiabilitiesCurrent None None None None None ... 4.686019e+09 NaN 4.860542e+09 4.413561e+09 4.664733e+09
AccountsPayableCurrent None None None None None ... 5.629850e+08 4.421940e+08 5.629850e+08 6.743470e+08 6.743470e+08
AccruedLiabilitiesCurrent None None None None None ... 4.774170e+08 4.774170e+08 1.037723e+09 8.430430e+08 9.865950e+08
DeferredRevenueCurrent None None None None None ... NaN NaN NaN NaN NaN
LiabilitiesCurrent None None None None None ... 6.487320e+09 6.487320e+09 7.257900e+09 6.855696e+09 6.855696e+09
ContentLiabilitiesNoncurrent None None None None None ... 3.759026e+09 NaN 3.759026e+09 3.206051e+09 3.208164e+09
LongTermDebtNoncurrent None None None None None ... 1.036006e+10 1.036006e+10 1.036006e+10 1.475926e+10 1.475926e+10
OtherLiabilitiesNoncurrent None None None None None ... 1.292310e+08 1.292310e+08 1.292310e+08 1.444276e+09 1.710948e+09
Liabilities None None None None None ... 2.151557e+10 2.073564e+10 2.408021e+10 2.665062e+10 2.639356e+10
CommitmentsAndContingencies None None None None None ... NaN NaN NaN NaN NaN
CommonStockValue None None None None None ... 2.315988e+09 2.315988e+09 2.315988e+09 2.793929e+09 2.793929e+09
AccumulatedOtherComprehensiveIncomeLossNetOfTax None None None None None ... -1.958200e+07 -1.958200e+07 -1.958200e+07 -2.352100e+07 -3.407200e+07
RetainedEarningsAccumulatedDeficit None None None None None ... 3.288885e+09 2.942359e+09 4.224779e+09 5.520816e+09 4.811749e+09
StockholdersEquity None None None None None ... 5.238765e+09 3.581956e+09 3.581956e+09 5.703058e+09 7.582157e+09
LiabilitiesAndStockholdersEquity None None None None None ... 2.597440e+10 2.597440e+10 2.597440e+10 3.505991e+10 3.717528e+10
PreferredStockParOrStatedValuePerShare None None None None None ... NaN NaN NaN NaN NaN
PreferredStockSharesAuthorized None None None None None ... NaN NaN NaN NaN NaN
PreferredStockSharesIssued None None None None None ... NaN NaN NaN NaN NaN
PreferredStockSharesOutstanding None None None None None ... NaN NaN NaN NaN NaN
PreferredStockValue None None None None None ... NaN NaN NaN NaN NaN
ContentLibraryNetCurrent None None None None None ... NaN NaN NaN NaN NaN
PrepaidContentCurrent None None None None None ... NaN NaN NaN NaN NaN
ContentLibraryNetNoncurrent None None None None None ... NaN NaN NaN NaN NaN
DueToRelatedPartiesNoncurrent None None None None None ... NaN NaN NaN NaN NaN
AdditionalPaidInCapitalCommonStock None None None None None ... NaN NaN NaN NaN NaN
ContractWithCustomerLiabilityCurrent None None None None None ... 8.086920e+08 7.608990e+08 9.155060e+08 9.247450e+08 1.029261e+09
ShortTermBorrowings None None None None None ... NaN NaN NaN 0.000000e+00 4.991610e+08
OtherPrepaidExpenseCurrent None None None None None ... NaN NaN NaN NaN NaN
ContentAccountsPayableCurrent None None None None None ... NaN NaN NaN NaN NaN
ContentAccountsPayableNoncurrent None None None None None ... NaN NaN NaN NaN NaN
SeniorLongTermNotes None None None None None ... NaN NaN NaN NaN NaN
RelatedPartyTransactionDueFromToRelatedParty None None None None None ... NaN NaN NaN NaN NaN
LicensingAssetCurrent None None None None None ... 5.151186e+09 NaN 5.151186e+09 NaN NaN
[46 rows x 44 columns] ,
"cash " : 2009q2 2009q3 2009q4 2010q1 2010q2 ... 2019q2 2019q3 2019q4 2020q2 2020q3
NetIncomeLoss None None None None None ... 2.901240e+08 384349000.0 4.028350e+08 7.090670e+08 2.706500e+08
AdditionstoStreamingContentAssets None None None None None ... 2.997746e+09 NaN 9.971141e+09 3.294275e+09 2.510782e+09
ChangeInStreamingContentLiabilities None None None None None ... -1.469800e+07 NaN -9.554800e+07 2.589450e+08 -1.084320e+08
CostofServicesAmortizationofStreamingContentAssets None None None None None ... 2.124686e+09 NaN 1.911767e+09 2.483385e+09 4.356601e+09
CostofServicesAmortizationofDVDContentAssets None None None None None ... 8.509000e+06 NaN 2.281900e+07 NaN NaN
... ... ... ... ... ... ... ... ... ... ... ...
ProceedsFromSaleOfAvailableForSaleSecuritiesDebt None None None None None ... NaN NaN NaN NaN NaN
InterestPaidNet None None None None None ... NaN NaN NaN NaN NaN
ProceedsfromPublicOfferingofCommonStock None None None None None ... NaN NaN NaN NaN NaN
ExtinguishmentOfDebtAmount None None None None None ... NaN NaN NaN NaN NaN
ForeignCurrencyTransactionLossBeforeTax None None None None None ... NaN NaN NaN NaN NaN
[71 rows x 44 columns] ,
"equity " : 2009q2 2009q3 2009q4 2010q1 2010q2 ... 2019q2 2019q3 2019q4 2020q2 2020q3
NetIncomeLoss None None None None None ... 3.440520e+08 6.147020e+08 1.279946e+09 3.440520e+08 2.706500e+08
OtherComprehensiveIncomeLossNetOfTaxPortionAttr... None None None None None ... NaN NaN NaN NaN NaN
StockIssuedDuringPeriodSharesStockOptionsExercised None None None None None ... NaN NaN NaN NaN NaN
StockIssuedDuringPeriodValueStockOptionsExercised None None None None None ... NaN NaN NaN NaN NaN
StockIssuedDuringPeriodSharesConversionOfConver... None None None None None ... NaN NaN NaN NaN NaN
StockIssuedDuringPeriodValueConversionOfConvert... None None None None None ... NaN NaN NaN NaN NaN
AdjustmentsToAdditionalPaidInCapitalSharebasedC... None None None None None ... NaN NaN NaN NaN NaN
AdjustmentsToAdditionalPaidInCapitalTaxEffectFr... None None None None None ... NaN NaN NaN NaN NaN
StockholdersEquity None None None None None ... 5.703058e+09 6.105548e+09 6.861505e+09 5.703058e+09 6.105548e+09
ComprehensiveIncomeNetOfTax None None None None None ... NaN NaN NaN NaN NaN
StockIssuedDuringPeriodValueEmployeeStockPurcha... None None None None None ... NaN NaN NaN NaN NaN
StockIssuedDuringPeriodValueNewIssues None None None None None ... NaN NaN NaN NaN NaN
StockRepurchasedAndRetiredDuringPeriodValue None None None None None ... NaN NaN NaN NaN NaN
StockRepurchasedAndRetiredDuringPeriodShares None None None None None ... NaN NaN NaN NaN NaN
CumulativeEffectOfNewAccountingPrincipleInPerio... None None None None None ... NaN NaN NaN NaN NaN
StockIssuedDuringPeriodSharesNewIssues None None None None None ... NaN NaN NaN NaN NaN
[16 rows x 44 columns] ,
"prices " : Open High Low Close Volume Dividends Stock Splits
Date
2002-05-23 1.156429 1.242857 1.145714 1.196429 104790000 0 0.0
2002-05-24 1.214286 1.225000 1.197143 1.210000 11104800 0 0.0
2002-05-28 1.213571 1.232143 1.157143 1.157143 6609400 0 0.0
2002-05-29 1.164286 1.164286 1.085714 1.103571 6757800 0 0.0
2002-05-30 1.107857 1.107857 1.071429 1.071429 10154200 0 0.0
... ... ... ... ... ... ... ...
2020-10-21 501.029999 506.850006 488.250000 489.049988 17405700 0 0.0
2020-10-22 494.690002 495.140015 482.000000 485.230011 6997900 0 0.0
2020-10-23 488.109985 490.059998 481.350006 488.279999 4927900 0 0.0
2020-10-26 487.029999 496.820007 478.899994 488.239990 6174200 0 0.0
2020-10-27 490.010010 490.000000 482.929993 488.929993 3547975 0 0.0
[4641 rows x 7 columns] ,
"actions " : Dividends Stock Splits
Date
2004-02-12 0.0 2.0
2015-07-15 0.0 7.0 ",
"dividends " : " Series([], Name: Dividends, dtype: int64) ",
"splits " : " Date
2004-02-12 2.0
2015-07-15 7.0
Name: Stock Splits, dtype: float64 ",
"major_holders " : " 0 1
0 1.62% % of Shares Held by All Insider
1 83.49% % of Shares Held by Institutions
2 84.86% % of Float Held by Institutions
3 1975 Number of Institutions Holding Shares ",
"institutional_holders " : " Holder Shares Date Reported % Out Value
0 Capital Research Global Investors 34111988 2020-06-29 0.0772 15522319019
1 Vanguard Group, Inc. (The) 34001284 2020-06-29 0.0770 15471944271
2 Blackrock Inc. 29171135 2020-06-29 0.0660 13274033270
3 FMR, LLC 22033243 2020-06-29 0.0499 10026006894
4 Price (T.Rowe) Associates Inc 20626346 2020-06-29 0.0467 9385812483
5 State Street Corporation 16613245 2020-06-29 0.0376 7559691004
6 Capital International Investors 15137030 2020-06-29 0.0343 6887954131
7 Capital World Investors 13676170 2020-06-29 0.0310 6223204396
8 Jennison Associates LLC 9099165 2020-06-29 0.0206 4140484041
9 Baillie Gifford and Company 7713485 2020-06-29 0.0175 3509944214 ,
"events " : 0 1
Earnings Date 2021-01-19 00:00:00 2021-01-25 00:00:00
Earnings Average 2.13 2.13
Earnings Low 1.82 1.82
Earnings High 2.3 2.3
Revenue Average 6379370000 6379370000
Revenue Low 6281000000 6281000000
Revenue High 6593000000 6593000000 ",
"recommendations " : " 0 1
Earnings Date 2021-01-19 00:00:00 2021-01-25 00:00:00
Earnings Average 2.13 2.13
Earnings Low 1.82 1.82
Earnings High 2.3 2.3
Revenue Average 6379370000 6379370000
Revenue Low 6281000000 6281000000
Revenue High 6593000000 6593000000 ",
"esg " : " Value
2020-10
palmOil False
controversialWeapons False
gambling False
socialScore 7.56
nuclear False
furLeather False
alcoholic False
gmo False
catholic False
socialPercentile None
peerCount 44
governanceScore 10.32
environmentPercentile None
animalTesting False
tobacco False
totalEsg 18.05
highestControversy 2
esgPerformance UNDER_PERF
coal False
pesticides False
adult False
percentile 14.5
peerGroup Media
smallArms False
environmentScore 0.16
governancePercentile None
militaryContract False,
"interest": NETFLIX INC isPartial
date
2015-11-22 57 False
2015-11-29 47 False
2015-12-06 45 False
2015-12-13 39 False
2015-12-20 32 False
... ... ...
2020-10-18 69 False
2020-10-25 57 False
2020-11-01 55 False
2020-11-08 63 False
2020-11-15 73 True
[261 rows x 2 columns]}
}
Sub Functions
The previous request pulls all data about a given company. This is obviously resource intensive. If you would like to request some subset of the full request, we advise using subfunctions. The following is a list of all available subfunctions.
u.prices(cik_or_ticker) # prices,volume, splits dataframe
u.dividends(cik_or_ticker) # dividend payouts dataframe
u.financial_statement(cik_or_ticker,kind="income") # income statement dataframe
u.financial_statement(cik_or_ticker,kind="balance") # balance sheet dataframe
u.financial_statement(cik_or_ticker,"cash") # cashflow statement dataframe
u.major_sharholders(cik_or_ticker) # major shareholders dataframe
u.major_sharholders(cik_or_ticker) # major shareholders dataframe
u.institutional_holders(cik_or_ticker") # institutional holders dataframe
u.events(cik_or_ticker) # date of events dataframe
u.splits(cik_or_ticker) # stock split events dataframe
u.recommendations(cik_or_ticker) # analyst recommendations dataframe
u.esg(cik_or_ticker) # esg metrics dataframe
u.interest(name) # google trends dataframe
Example Use Case
I really want to demonstrate the beauty of what we have here since this is often difficult when looking at thousands of numeric datatables. Let's take a very naive peek by plotting various dataframes as timeseries.
The following is a start to finish example of how one might plot the financial statements and price series of the first five companies in the universe.
Here's how we'd implement that:
from equities import Universe
import matplotlib.pyplot as plt
u = Universe()
k,f,s = 'bar',(10,7),True
for cik in u.ciks[:5]:
c = u.company(cik)
income = c['income']
if not income.empty:
income.T.plot(
kind=k,
figsize=f,
stacked=s)
balance = c['balance']
if not balance.empty:
balance.T.plot(
kind=k,
figsize=f,
stacked=s)
cash = c['cash']
if not cash.empty:
cash.T.plot(
kind=k,
figsize=f,
stacked=s)
prices = c['prices']
if not prices.empty:
prices.drop('Volume',axis=1).plot(
kind='line',
figsize=f)
# Notice that the code above is expensive since we are interested in a few fields
# within the results "c", using sub functions would be much more efficient.
plt.show()
Donate:
Consider buying me a coffee to fund the future development of this project.
bitcoin wallet address: 3LU5MEaAXRJoCo6vx67g1Jj7qDFRKhMs5t
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
equities-4.2.6.tar.gz
(24.6 kB
view hashes)
Built Distribution
equities-4.2.6-py3-none-any.whl
(11.5 kB
view hashes)
