The API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. This is 1 of the most comprehensive financial API available on the market.
Base URL: /api/v1
Swagger schema: Download
All GET request require a token parameter token=apiKey
in the URL or a header X-Finnhub-Token : apiKey
. You can find your API Key under Dashboard. If you are logged in, your API key will be automatically used in the examples so you can copy and paste them as is.
If your limit is exceeded, you will receive a response with status code 429
.
On top of all plan's limit, there is a 30 API calls/ second limit.
Finsheet is the official spreadsheet's plugin partner using fundamental data and estimates data from Finnhub. If you are looking to complement the stock price data you already got directly from Excel and Google Sheets with some advanced data, Finsheet's Excel and Google Sheets plugin offer an affordable way to access global fundamentals and estimates right in your spreadsheet.
We have been incredibly humbled by the support of the open-source community. Beside these incredible projects, here are our own official libraries:
Language | Homepage |
---|---|
Python | finnhub-python |
Go | finnhub-go |
Javascript | Finnhub NPM |
Ruby | Finnhub Ruby |
Kotlin | Finnhub Kotlin |
PHP | Finnhub PHP |
We understand the importance of data for students, researchers,and investors. That's why at Finnhub, we have decided to create multiple Open Datasets for the community which can be downloaded in bulk below:
Datasets | Download |
---|---|
SEC Financials As Reported | Kaggle |
SEC Filings Metadata | Kaggle |
S&P 500 futures tick data | Kaggle |
Stream real-time trades for US stocks, forex and crypto. Trades might not be available for some forex and crypto exchanges. In that case, a price update will be sent with volume = 0. A message can contain multiple trades. 1 API key can only open 1 connection at a time. Real-time US market data is provided by IEX. Cross-connect and real-time data for international markets are available for Enterprise clients via our partners. Contact us to learn more.
The following FX brokers do not support streaming: FXCM, Forex.com, FHFX. To get latest price for FX, please use the Forex Candles or All Rates endpoint.
Method: Websocket
Examples:
Response Attributes:
Message type.
List of trades or price updates.
Symbol.
Last price.
UNIX milliseconds timestamp.
Volume.
List of trade conditions. A comprehensive list of trade conditions code can be found here
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
#https://pypi.org/project/websocket_client/
import websocket
def on_message(ws, message):
print(message)
def on_error(ws, error):
print(error)
def on_close(ws):
print("### closed ###")
def on_open(ws):
ws.send('{"type":"subscribe","symbol":"AAPL"}')
ws.send('{"type":"subscribe","symbol":"AMZN"}')
ws.send('{"type":"subscribe","symbol":"BINANCE:BTCUSDT"}')
ws.send('{"type":"subscribe","symbol":"IC MARKETS:1"}')
if __name__ == "__main__":
websocket.enableTrace(True)
ws = websocket.WebSocketApp("wss://ws.finnhub.io?token=",
on_message = on_message,
on_error = on_error,
on_close = on_close)
ws.on_open = on_open
ws.run_forever()
1 2 3 4 5 6 7 8 9 10 11
{ "data": [ { "p": 7296.89, "s": "BINANCE:BTCUSDT", "t": 1575526691134, "v": 0.011467 } ], "type": "trade" }
Stream real-time news for US and Canadian stocks.
Method: Websocket
Premium: Premium Access Required
Examples:
Response Attributes:
Message type: news
.
List of news.
News category.
Published time in UNIX timestamp.
News headline.
News ID.
Thumbnail image URL.
Related stocks and companies mentioned in the article.
News source.
News summary.
URL of the original article.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
#https://pypi.org/project/websocket_client/
import websocket
def on_message(ws, message):
print(message)
def on_error(ws, error):
print(error)
def on_close(ws):
print("### closed ###")
def on_open(ws):
ws.send('{"type":"subscribe-news","symbol":"AAPL"}')
ws.send('{"type":"subscribe-news","symbol":"AMZN"}')
ws.send('{"type":"subscribe-news","symbol":"MSFT"}')
ws.send('{"type":"subscribe-news","symbol":"BYND"}')
if __name__ == "__main__":
websocket.enableTrace(True)
ws = websocket.WebSocketApp("wss://ws.finnhub.io?token=",
on_message = on_message,
on_error = on_error,
on_close = on_close)
ws.on_open = on_open
ws.run_forever()
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
{ "data": [ { "category": "company", "datetime": 1679920200, "headline": "CanAlaska Uranium Announces Airborne Electromagnetic Survey Completed at Geikie Project in Athabasca Basin", "id": 119440189, "image": "https://media.zenfs.com/en/newsfile_64/0522ee5d9e134e6f966c6ecdfc50fb46", "related": "CVVUF", "source": "Yahoo", "summary": "Multiple Priority Targets Associated with Regional Scale Fault Structures Preparation Underway for First Drill ProgramDrilling Continues at West McArthur JV and Key Extension ProjectsVancouver, British Columbia--(Newsfile Corp. - March 27, 2023) - CanAlaska Uranium Ltd. (TSXV: CVV) (OTCQX: CVVUF) (FSE: DH7N) (\"CanAlaska\" or the \"Company\") is pleased to announce completion of a high-resolution airborne Versatile Time Domain Electromagnetic (\"VTEM Plus\") survey on it's 60%-owned Geikie project in", "url": "https://finance.yahoo.com/news/canalaska-uranium-announces-airborne-electromagnetic-123000318.html" } ], "type": "news" }
Stream real-time press releases data for global companies. This feature is only available for Enterprise users.
Method: Websocket
Premium: Premium Access Required
Examples:
Response Attributes:
Message type: news
.
List of news.
Published time in UNIX timestamp.
News headline.
Related stocks and companies mentioned in the article.
URL to download the full-text data.
URL to read the article.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
#https://pypi.org/project/websocket_client/
import websocket
def on_message(ws, message):
print(message)
def on_error(ws, error):
print(error)
def on_close(ws):
print("### closed ###")
def on_open(ws):
ws.send('{"type":"subscribe-pr","symbol":"AAPL"}')
ws.send('{"type":"subscribe-pr","symbol":"AMZN"}')
ws.send('{"type":"subscribe-pr","symbol":"MSFT"}')
ws.send('{"type":"subscribe-pr","symbol":"BYND"}')
if __name__ == "__main__":
websocket.enableTrace(True)
ws = websocket.WebSocketApp("wss://ws.finnhub.io?token=",
on_message = on_message,
on_error = on_error,
on_close = on_close)
ws.on_open = on_open
ws.run_forever()
1 2 3 4 5 6 7 8 9 10 11 12
{ "data": [ { "datetime": 1637696940, "fullText": "https://static2.finnhub.io/file/publicdatany/pr/0eb7fb4118ec53204755719b4cc4d57e9370d3caa2fa15d5e7a8f3b4d99cc881.html", "headline": "STOCKHOLDER ALERT: Monteverde & Associates PC Continues to Investigate the Following Merger", "symbol": "PAE,ZIXI,KRA", "url": "https://finnhub.io/api/press-releases?id=0eb7fb4118ec53204755719b4cc4d57e9370d3caa2fa15d5e7a8f3b4d99cc881" } ], "type": "pr" }
Search for best-matching symbols based on your query. You can input anything from symbol, security's name to ISIN and Cusip.
Method: GET
Examples:
Arguments:
Query text can be symbol, name, isin, or cusip.
Exchange limit.
Response Attributes:
Number of results.
Array of search results.
Symbol description
Display symbol name.
Unique symbol used to identify this symbol used in /stock/candle
endpoint.
Security type.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.symbol_lookup('apple'))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29
{ "count": 4, "result": [ { "description": "APPLE INC", "displaySymbol": "AAPL", "symbol": "AAPL", "type": "Common Stock" }, { "description": "APPLE INC", "displaySymbol": "AAPL.SW", "symbol": "AAPL.SW", "type": "Common Stock" }, { "description": "APPLE INC", "displaySymbol": "APC.BE", "symbol": "APC.BE", "type": "Common Stock" }, { "description": "APPLE INC", "displaySymbol": "APC.DE", "symbol": "APC.DE", "type": "Common Stock" } ] }
List supported stocks. We use the following symbology to identify stocks on Finnhub Exchange_Ticker.Exchange_Code
. A list of supported exchange codes can be found here.
Method: GET
Examples:
/stock/symbol?exchange=US&mic=XNYS
Arguments:
Exchange you want to get the list of symbols from. List of exchange codes can be found here.
Filter by MIC code.
Filter by security type used by OpenFigi standard.
Filter by currency.
Response Attributes:
Price's currency. This might be different from the reporting currency of fundamental data.
Symbol description
Display symbol name.
FIGI identifier.
ISIN. This field is only available for EU stocks and selected Asian markets. Entitlement from Finnhub is required to access this field.
Primary exchange's MIC.
Global Share Class FIGI.
Unique symbol used to identify this symbol used in /stock/candle
endpoint.
Alternative ticker for exchanges with multiple tickers for 1 stock such as BSE.
Security type.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.stock_symbols('US'))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29
[ { "currency": "USD", "description": "UAN POWER CORP", "displaySymbol": "UPOW", "figi": "BBG000BGHYF2", "mic": "OTCM", "symbol": "UPOW", "type": "Common Stock" }, { "currency": "USD", "description": "APPLE INC", "displaySymbol": "AAPL", "figi": "BBG000B9Y5X2", "mic": "XNGS", "symbol": "AAPL", "type": "Common Stock" }, { "currency": "USD", "description": "EXCO TECHNOLOGIES LTD", "displaySymbol": "EXCOF", "figi": "BBG000JHDDS8", "mic": "OOTC", "symbol": "EXCOF", "type": "Common Stock" } ]
Get current market status for global exchanges (whether exchanges are open or close).
Method: GET
Examples:
/stock/market-status?exchange=US
/stock/market-status?exchange=L
Arguments:
Exchange code.
Response Attributes:
Exchange.
Holiday event.
Whether the market is open at the moment.
Market session. Can be 1 of the following values: pre-market
,regular
,post-market
or null
if the market is closed.
Current timestamp.
Timezone.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.market_status(exchange='US'))
1 2 3 4 5 6 7 8
{ "exchange": "US", "holiday": null, "isOpen": false, "session": "pre-market", "timezone": "America/New_York", "t": 1697018041 }
Get a list of holidays for global exchanges.
Method: GET
Examples:
/stock/market-holiday?exchange=US
/stock/market-holiday?exchange=L
Arguments:
Exchange code.
Response Attributes:
Array of holidays.
Date.
Holiday's name.
Trading hours for this day if the market is partially closed only.
Exchange.
Timezone.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.market_holiday(exchange='US'))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
{ "data": [ { "eventName": "Christmas", "atDate": "2023-12-25", "tradingHour": "" }, { "eventName": "Independence Day", "atDate": "2023-07-03", "tradingHour": "09:30-13:00" } ], "exchange": "US", "timezone": "America/New_York" }
Get general information of a company. You can query by symbol, ISIN or CUSIP
Method: GET
Premium: Premium Access Required
Examples:
/stock/profile?isin=US5949181045
/stock/profile?cusip=023135106
Arguments:
Symbol of the company: AAPL e.g.
ISIN
CUSIP
Response Attributes:
Address of company's headquarter.
Company name alias.
City of company's headquarter.
Country of company's headquarter.
Currency used in company filings and financials.
CUSIP number.
Company business summary.
Number of employee.
Currency used in Estimates data.
Listed exchange.
Finnhub industry classification.
Industry group.
Industry.
Sector.
Sub-industry.
IPO date.
Investor relations website.
ISIN number.
LEI number.
Logo image.
Currency used in market capitalization.
Market Capitalization.
NAICS industry.
NAICS national industry.
NAICS sector.
NAICS subsector.
Company name.
Company phone number.
Sedol number.
Number of oustanding shares.
State of company's headquarter.
Company symbol/ticker as used on the listed exchange.
Company website.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.company_profile(symbol='AAPL'))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30
{ "address": "1 Apple Park Way", "city": "CUPERTINO", "country": "US", "currency": "USD", "cusip": "", "sedol":"2046251", "description": "Apple Inc. is an American multinational technology company headquartered in Cupertino, California, that designs, develops, and sells consumer electronics, computer software, and online services. It is considered one of the Big Four technology companies, alongside Amazon, Google, and Microsoft. The company's hardware products include the iPhone smartphone, the iPad tablet computer, the Mac personal computer, the iPod portable media player, the Apple Watch smartwatch, the Apple TV digital media player, the AirPods wireless earbuds and the HomePod smart speaker. Apple's software includes the macOS, iOS, iPadOS, watchOS, and tvOS operating systems, the iTunes media player, the Safari web browser, the Shazam acoustic fingerprint utility, and the iLife and iWork creativity and productivity suites, as well as professional applications like Final Cut Pro, Logic Pro, and Xcode. Its online services include the iTunes Store, the iOS App Store, Mac App Store, Apple Music, Apple TV+, iMessage, and iCloud. Other services include Apple Store, Genius Bar, AppleCare, Apple Pay, Apple Pay Cash, and Apple Card.", "employeeTotal": "137000", "exchange": "NASDAQ/NMS (GLOBAL MARKET)", "ggroup": "Technology Hardware & Equipment", "gind": "Technology Hardware, Storage & Peripherals", "gsector": "Information Technology", "gsubind": "Technology Hardware, Storage & Peripherals", "ipo": "1980-12-12", "isin": "", "marketCapitalization": 1415993, "naics": "Communications Equipment Manufacturing", "naicsNationalIndustry": "Radio and Television Broadcasting and Wireless Communications Equipment Manufacturing", "naicsSector": "Manufacturing", "naicsSubsector": "Computer and Electronic Product Manufacturing", "name": "Apple Inc", "phone": "14089961010", "shareOutstanding": 4375.47998046875, "state": "CALIFORNIA", "ticker": "AAPL", "weburl": "https://www.apple.com/", "logo": "https://static.finnhub.io/logo/87cb30d8-80df-11ea-8951-00000000092a.png", "finnhubIndustry":"Technology" }
Get general information of a company. You can query by symbol, ISIN or CUSIP. This is the free version of Company Profile.
Method: GET
Examples:
/stock/profile2?isin=US5949181045
/stock/profile2?cusip=023135106
Arguments:
Symbol of the company: AAPL e.g.
ISIN
CUSIP
Response Attributes:
Country of company's headquarter.
Currency used in company filings.
Listed exchange.
Finnhub industry classification.
IPO date.
Logo image.
Market Capitalization.
Company name.
Company phone number.
Number of oustanding shares.
Company symbol/ticker as used on the listed exchange.
Company website.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.company_profile2(symbol='AAPL'))
1 2 3 4 5 6 7 8 9 10 11 12 13 14
{ "country": "US", "currency": "USD", "exchange": "NASDAQ/NMS (GLOBAL MARKET)", "ipo": "1980-12-12", "marketCapitalization": 1415993, "name": "Apple Inc", "phone": "14089961010", "shareOutstanding": 4375.47998046875, "ticker": "AAPL", "weburl": "https://www.apple.com/", "logo": "https://static.finnhub.io/logo/87cb30d8-80df-11ea-8951-00000000092a.png", "finnhubIndustry":"Technology" }
Get a list of company's executives and members of the Board.
Method: GET
Premium: Premium Access Required
Examples:
Arguments:
Symbol of the company: AAPL.
Response Attributes:
Array of company's executives and members of the Board.
Age
Total compensation
Compensation currency
Executive name
Sex
Year first appointed as executive/director of the company
Title
Company symbol.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.company_executive('AAPL'))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22
{ "executive": [ { "age": 56, "compensation": 25209637, "currency": "USD", "name": "Luca Maestri", "position": "Senior Vice President and Chief Financial Officer", "sex": "male", "since": "2014" }, { "age": 59, "compensation": 11555466, "currency": "USD", "name": "Mr. Timothy Cook", "position": "Director and Chief Executive Officer", "sex": "male", "since": "2011" } ] }
Get latest market news.
Method: GET
Examples:
Arguments:
This parameter can be 1 of the following values general, forex, crypto, merger
.
Use this field to get only news after this ID. Default to 0
Response Attributes:
News category.
Published time in UNIX timestamp.
News headline.
News ID. This value can be used for minId
params to get the latest news only.
Thumbnail image URL.
Related stocks and companies mentioned in the article.
News source.
News summary.
URL of the original article.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.general_news('general', min_id=0))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35
[ { "category": "technology", "datetime": 1596589501, "headline": "Square surges after reporting 64% jump in revenue, more customers using Cash App", "id": 5085164, "image": "https://image.cnbcfm.com/api/v1/image/105569283-1542050972462rts25mct.jpg?v=1542051069", "related": "", "source": "CNBC", "summary": "Shares of Square soared on Tuesday evening after posting better-than-expected quarterly results and strong growth in its consumer payments app.", "url": "https://www.cnbc.com/2020/08/04/square-sq-earnings-q2-2020.html" }, { "category": "business", "datetime": 1596588232, "headline": "B&G Foods CEO expects pantry demand to hold up post-pandemic", "id": 5085113, "image": "https://image.cnbcfm.com/api/v1/image/106629991-1595532157669-gettyimages-1221952946-362857076_1-5.jpeg?v=1595532242", "related": "", "source": "CNBC", "summary": "\"I think post-Covid, people will be working more at home, which means people will be eating more breakfast\" and other meals at home, B&G CEO Ken Romanzi said.", "url": "https://www.cnbc.com/2020/08/04/bg-foods-ceo-expects-pantry-demand-to-hold-up-post-pandemic.html" }, { "category": "top news", "datetime": 1596584406, "headline": "Anthony Levandowski gets 18 months in prison for stealing Google self-driving car files", "id": 5084850, "image": "https://image.cnbcfm.com/api/v1/image/106648265-1596584130509-UBER-LEVANDOWSKI.JPG?v=1596584247", "related": "", "source": "CNBC", "summary": "A U.S. judge on Tuesday sentenced former Google engineer Anthony Levandowski to 18 months in prison for stealing a trade secret from Google related to self-driving cars months before becoming the head of Uber Technologies Inc's rival unit.", "url": "https://www.cnbc.com/2020/08/04/anthony-levandowski-gets-18-months-in-prison-for-stealing-google-self-driving-car-files.html" } }]
List latest company news by symbol. This endpoint is only available for North American companies.
Method: GET
Free Tier: 1 year of historical news and new updates
Examples:
/company-news?symbol=AAPL&from=2023-08-15&to=2023-08-20
Arguments:
Company symbol.
From date YYYY-MM-DD
.
To date YYYY-MM-DD
.
Response Attributes:
News category.
Published time in UNIX timestamp.
News headline.
News ID. This value can be used for minId
params to get the latest news only.
Thumbnail image URL.
Related stocks and companies mentioned in the article.
News source.
News summary.
URL of the original article.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.company_news('AAPL', _from="2020-06-01", to="2020-06-10"))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35
[ { "category": "company news", "datetime": 1569550360, "headline": "More sops needed to boost electronic manufacturing: Top govt official More sops needed to boost electronic manufacturing: Top govt official. More sops needed to boost electronic manufacturing: Top govt official More sops needed to boost electronic manufacturing: Top govt official", "id": 25286, "image": "https://img.etimg.com/thumb/msid-71321314,width-1070,height-580,imgsize-481831,overlay-economictimes/photo.jpg", "related": "AAPL", "source": "The Economic Times India", "summary": "NEW DELHI | CHENNAI: India may have to offer electronic manufacturers additional sops such as cheap credit and incentives for export along with infrastructure support in order to boost production and help the sector compete with China, Vietnam and Thailand, according to a top government official.These incentives, over and above the proposed reduction of corporate tax to 15% for new manufacturing units, are vital for India to successfully attract companies looking to relocate manufacturing facilities.“While the tax announcements made last week send a very good signal, in order to help attract investments, we will need additional initiatives,” the official told ET, pointing out that Indian electronic manufacturers incur 8-10% higher costs compared with other Asian countries.Sops that are similar to the incentives for export under the existing Merchandise Exports from India Scheme (MEIS) are what the industry requires, the person said.MEIS gives tax credit in the range of 2-5%. An interest subvention scheme for cheaper loans and a credit guarantee scheme for plant and machinery are some other possible measures that will help the industry, the official added.“This should be 2.0 (second) version of the electronic manufacturing cluster (EMC) scheme, which is aimed at creating an ecosystem with an anchor company plus its suppliers to operate in the same area,” he said.Last week, finance minister Nirmala Sitharaman announced a series of measures to boost economic growth including a scheme allowing any new manufacturing company incorporated on or after October 1, to pay income tax at 15% provided the company does not avail of any other exemption or incentives.", "url": "https://economictimes.indiatimes.com/industry/cons-products/electronics/more-sops-needed-to-boost-electronic-manufacturing-top-govt-official/articleshow/71321308.cms" }, { "category": "company news", "datetime": 1569528720, "headline": "How to disable comments on your YouTube videos in 2 different ways", "id": 25287, "image": "https://amp.businessinsider.com/images/5d8d16182e22af6ab66c09e9-1536-768.jpg", "related": "AAPL", "source": "Business Insider", "summary": "You can disable comments on your own YouTube video if you don't want people to comment on it. It's easy to disable comments on YouTube by adjusting the settings for one of your videos in the beta or classic version of YouTube Studio. Visit Business Insider's homepage for more stories . The comments section has a somewhat complicated reputation for creators, especially for those making videos on YouTube . While it can be useful to get the unfiltered opinions of your YouTube viewers and possibly forge a closer connection with them, it can also open you up to quite a bit of negativity. So it makes sense that there may be times when you want to turn off the feature entirely. Just keep in mind that the action itself can spark conversation. If you decide that you don't want to let people leave comments on your YouTube video, here's how to turn off the feature, using either the classic or beta version of the creator studio: How to disable comments on YouTube in YouTube Studio (beta) 1. Go to youtube.com and log into your account, if necessary. 2.", "url": "https://www.businessinsider.com/how-to-disable-comments-on-youtube" }, { "category": "company news", "datetime": 1569526180, "headline": "Apple iPhone 11 Pro Teardowns Look Encouraging for STMicro and Sony", "id": 25341, "image": "http://s.thestreet.com/files/tsc/v2008/photos/contrib/uploads/ba140938-d409-11e9-822b-fda891ce1fc1.png", "related": "AAPL", "source": "TheStreet", "summary": "STMicroelectronics and Sony each appear to be supplying four chips for Apple's latest flagship iPhones. Many other historical iPhone suppliers also make appearances in the latest teardowns….STM", "url": "https://realmoney.thestreet.com/investing/technology/iphone-11-pro-teardowns-look-encouraging-for-stmicro-sony-15105767" }, ]
Get latest major press releases of a company. This data can be used to highlight the most significant events comprised of mostly press releases sourced from the exchanges, BusinessWire, AccessWire, GlobeNewswire, Newsfile, and PRNewswire.
Full-text press releases data is available for Enterprise clients. Contact Us to learn more.
Method: GET
Premium: Premium Access Required
Examples:
/press-releases?symbol=IBM&from=2019-11-01&to=2020-02-15
Arguments:
Company symbol.
From time: 2020-01-01.
To time: 2020-01-05.
Response Attributes:
Array of major developments.
Published time in YYYY-MM-DD HH:MM:SS
format.
Development description.
Development headline.
Company symbol.
URL.
Company symbol.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.press_releases('AAPL'))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
{ "majorDevelopment": [ { "symbol": "AAPL", "datetime": "2020-08-04 17:06:32", "headline": "27-inch iMac Gets a Major Update", "description": "CUPERTINO, Calif.--(BUSINESS WIRE)-- Apple today announced a major update to its 27-inch iMac®. By far the most powerful and capable iMac ever, it features faster Intel processors up to 10 cores, double the memory capacity, next-generation AMD graphics, superfast SSDs across the line with four times the storage capacity, a new nano-texture glass option for an even more stunning Retina® 5K display, a 1080p FaceTime® HD camera, higher fidelity speakers, and studio-quality mics. For the consumer using their iMac all day, every day, to the aspiring creative looking for inspiration, to the serious pro pushing the limits of their creativity, the new 27-inch iMac delivers the ultimate desktop experience that is now better in every way." }, { "symbol": "AAPL", "datetime": "2020-03-28 09:41:23", "headline": "Apple Central World Opens Friday in Thailand", "description": "BANGKOK--(BUSINESS WIRE)-- Apple® today previewed Apple Central World, its second and largest retail location in Thailand. Nestled in the heart of Ratchaprasong, Bangkok’s iconic intersection, the store provides a completely new and accessible destination within the lively city. Apple Central World’s distinctive architecture is brought to life with the first-ever all-glass design, housed under a cantilevered Tree Canopy roof. Once inside, customers can travel between two levels via a spiral staircase that wraps around a timber core, or riding a unique cylindrical elevator clad in mirror-polished stainless steel. Guests can enter from the ground or upper level, which provides a direct connection to the Skytrain and the city’s largest shopping center. The outdoor plaza offers a place for the community to gather, with benches and large Terminalia trees surrounding the space." } ], "symbol": "AAPL" }
Get company's news sentiment and statistics. This endpoint is only available for US companies.
Method: GET
Premium: Premium Access Required
Examples:
Arguments:
Company symbol.
Response Attributes:
Statistics of company news in the past week.
News score.
Sector average bullish percent.
Sectore average score.
News sentiment.
Requested symbol.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.news_sentiment('AAPL'))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
{ "buzz": { "articlesInLastWeek": 20, "buzz": 0.8888, "weeklyAverage": 22.5 }, "companyNewsScore": 0.9166, "sectorAverageBullishPercent": 0.6482, "sectorAverageNewsScore": 0.5191, "sentiment": { "bearishPercent": 0, "bullishPercent": 1 }, "symbol": "V" }
Get company peers. Return a list of peers operating in the same country and sector/industry.
Method: GET
Examples:
/stock/peers?symbol=F&grouping=industry
Arguments:
Symbol of the company: AAPL.
Specify the grouping criteria for choosing peers.Supporter values: sector
, industry
, subIndustry
. Default to subIndustry
.
Response Attributes:
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.company_peers('AAPL'))
1 2 3 4 5 6 7 8 9 10 11 12
[ "AAPL", "EMC", "HPQ", "DELL", "WDC", "HPE", "NTAP", "CPQ", "SNDK", "SEG" ]
Get company basic financials such as margin, P/E ratio, 52-week high/low etc.
Method: GET
Examples:
/stock/metric?symbol=AAPL&metric=all
Arguments:
Symbol of the company: AAPL.
Metric type. Can be 1 of the following values all
Response Attributes:
Map key-value pair of key ratios and metrics.
Metric type.
Map key-value pair of time-series ratios.
Symbol of the company.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.company_basic_financials('AAPL', 'all'))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46
{ "series": { "annual": { "currentRatio": [ { "period": "2019-09-28", "v": 1.5401 }, { "period": "2018-09-29", "v": 1.1329 } ], "salesPerShare": [ { "period": "2019-09-28", "v": 55.9645 }, { "period": "2018-09-29", "v": 53.1178 } ], "netMargin": [ { "period": "2019-09-28", "v": 0.2124 }, { "period": "2018-09-29", "v": 0.2241 } ] } }, "metric": { "10DayAverageTradingVolume": 32.50147, "52WeekHigh": 310.43, "52WeekLow": 149.22, "52WeekLowDate": "2019-01-14", "52WeekPriceReturnDaily": 101.96334, "beta": 1.2989, }, "metricType": "all", "symbol": "AAPL" }
Get a full list of shareholders of a company in descending order of the number of shares held. Data is sourced from 13F form
, Schedule 13D
and 13G
for US market, UK Share Register
for UK market, SEDI
for Canadian market and equivalent filings for other international markets.
Method: GET
Premium: Premium Access Required
Examples:
/stock/ownership?symbol=AAPL&limit=20
Arguments:
Symbol of the company: AAPL.
Limit number of results. Leave empty to get the full list.
Response Attributes:
Array of investors with detailed information about their holdings.
Number of share changed (net buy or sell) from the last period.
Filing date.
Investor's name.
Number of shares held by the investor.
Symbol of the company.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.ownership('AAPL', limit=5))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
{ "ownership": [ { "name": "The Vanguard Group, Inc.", "share": 329323420, "change": -1809077, "filingDate": "2019-12-31" }, { "name": "BRK.A | Berkshire Hathaway Inc.", "share": 245155570, "change": -3683113, "filingDate": "2019-12-31" }, { "name": "BlackRock Institutional Trust Co NA", "share": 187354850, "change": -2500563, "filingDate": "2020-03-31" } ], "symbol": "AAPL" }
Get a full list fund and institutional investors of a company in descending order of the number of shares held. Data is sourced from 13F form
, Schedule 13D
and 13G
for US market, UK Share Register
for UK market, SEDI
for Canadian market and equivalent filings for other international markets.
Method: GET
Premium: Premium Access Required
Examples:
/stock/fund-ownership?symbol=TSLA&limit=20
Arguments:
Symbol of the company: AAPL.
Limit number of results. Leave empty to get the full list.
Response Attributes:
Array of investors with detailed information about their holdings.
Number of share changed (net buy or sell) from the last period.
Filing date.
Investor's name.
Percent of the fund's portfolio comprised of the company's share.
Number of shares held by the investor.
Symbol of the company.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.fund_ownership('AAPL', limit=5))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26
{ "ownership": [ { "name": "AGTHX | American Funds Growth Fund of America", "share": 5145353, "change": 57427, "filingDate": "2020-03-31", "portfolioPercent": 1.88 }, { "name": "Vanguard Total Stock Market Index Fund", "share": 4227464, "change": 73406, "filingDate": "2020-03-31", "portfolioPercent": 0.45 }, { "name": "ANWPX | American Funds New Perspective", "share": 3377612, "change": 0, "filingDate": "2020-03-31", "portfolioPercent": 2.64 } ], "symbol": "TSLA" }
Get a list of well-known institutional investors. Currently support 60+ profiles.
Method: GET
Premium: Premium Access Required
Examples:
Arguments:
Filter by CIK. Leave blank to get the full list.
Response Attributes:
CIK.
Array of investors.
Investor's company CIK.
Firm type.
Manager.
Investing philosophy.
Profile info.
Profile image.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.institutional_profile()
1 2 3 4 5 6 7 8 9 10 11 12 13
{ "cik": "1067983", "data": [ { "cik": "1067983", "firmType": "Institutional Investment Manager", "manager": "Warren Buffett", "philosophy": "Value investing is the hallmark of Warren Buffett's investment approach. By choosing stocks whose share price is below their intrinsic or book value, value investors can increase their returns. This suggests that the stock will increase in value going forward and that the market is now undervaluing it. Only enterprises that Buffett is familiar with are chosen for investment by Berkshire, and a safety margin is always required.", "profile": "Warren Edward Buffett (born August 30, 1930) is an American business magnate, investor, and philanthropist. He is currently the chairman and CEO of Berkshire Hathaway. He is one of the most successful investors in the world and has a net worth of over $103 billion as of August 2022, making him the world's seventh-wealthiest person. Buffett has been the chairman and largest shareholder of Berkshire Hathaway since 1970. He has been referred to as the \"Oracle\" or \"Sage\" of Omaha by global media. He is noted for his adherence to value investing, and his personal frugality despite his immense wealth. Buffett is a philanthropist, having pledged to give away 99 percent of his fortune to philanthropic causes, primarily via the Bill \u0026 Melinda Gates Foundation. He founded The Giving Pledge in 2010 with Bill Gates, whereby billionaires pledge to give away at least half of their fortunes.", "profileImg": "https://static4.finnhub.io/file/publicdatany5/guru_profile_pic/1067983.jpg" } ] }
Get the holdings/portfolio data of institutional investors from 13-F filings. Limit to 1 year of data at a time. You can get a list of supported CIK here.
Method: GET
Premium: Premium Access Required
Examples:
/institutional/portfolio?cik=1000097&from=2022-05-01&to=2022-09-01
Arguments:
Fund's CIK.
From date YYYY-MM-DD
.
To date YYYY-MM-DD
.
Response Attributes:
CIK.
Array of positions.
Filing date.
Array of positions.
Number of shares change.
CUSIP.
Position's name.
Number of shares with no voting rights.
Percentage of portfolio.
put
or call
for options.
Number of shares.
Number of shares with shared voting rights.
Number of shares with sole voting rights.
Symbol.
Position value.
Report date.
Investor's name.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.institutional_portfolio(cik="1000097", _from="2022-10-01", to="2022-10-11"))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36
{ "cik": "1000097", "data": [ { "filingDate": "2022-06-30", "portfolio": [ { "change": -41600, "name": "ABBOTT LABS", "noVoting": 0, "percentage": 0, "putCall": "", "share": 0, "sharedVoting": 0, "soleVoting": 41600, "symbol": "ABT", "value": 0 }, { "change": -275000, "name": "ADICET BIO INC", "noVoting": 0, "percentage": 0, "putCall": "", "share": 0, "sharedVoting": 0, "soleVoting": 275000, "symbol": "ACET", "value": 0 } ], "reportDate": "2022-06-30" } ], "name": "KINGDON CAPITAL MANAGEMENT, L.L.C." }
Get a list institutional investors' positions for a particular stock overtime. Data from 13-F filings. Limit to 1 year of data at a time.
Method: GET
Premium: Premium Access Required
Examples:
/institutional/ownership?symbol=TSLA&from=2022-09-01&to=2022-10-30
Arguments:
Filter by symbol.
Filter by CUSIP.
From date YYYY-MM-DD
.
To date YYYY-MM-DD
.
Response Attributes:
Cusip.
Array of institutional investors.
Array of institutional investors.
Number of shares change.
Investor's company CIK.
Firm's name.
Number of shares with no voting rights.
Percentage of portfolio.
put
or call
for options.
News score.
Number of shares with shared voting rights.
Number of shares with sole voting rights.
Position value.
Report date.
Symbol.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.institutional_ownership(symbol="TSLA", cusip="", _from="2022-10-01", to="2022-10-11"))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
{ "cusip": "023135106", "data": [ { "ownership": [ { "change": null, "cik": "1000097", "name": "KINGDON CAPITAL MANAGEMENT, L.L.C.", "noVoting": 0, "percentage": 6.23893, "putCall": "", "share": 11250, "sharedVoting": 0, "soleVoting": 11250, "value": 36674000 } ], "reportDate": "2022-03-31" } ], "symbol": "AMZN" }
Company insider transactions data sourced from Form 3,4,5
, SEDI and relevant companies' filings. This endpoint covers US, UK, Canada, Australia, India, and all major EU markets. Limit to 100 transactions per API call.
Method: GET
Examples:
/stock/insider-transactions?symbol=TSLA&limit=20
/stock/insider-transactions?symbol=AC.TO
Arguments:
Symbol of the company: AAPL. Leave this param blank to get the latest transactions.
From date: 2020-03-15.
To date: 2020-03-16.
Response Attributes:
Array of insider transactions.
Number of share changed from the last period. A positive value suggests a BUY
transaction. A negative value suggests a SELL
transaction.
Filing date.
Insider's name.
Number of shares held after the transaction.
Symbol.
Transaction code. A list of codes and their meanings can be found here.
Transaction date.
Average transaction price.
Symbol of the company.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.stock_insider_transactions('AAPL', '2021-01-01', '2021-03-01'))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32
{ "data": [ { "name": "Kirkhorn Zachary", "share": 57234, "change": -1250, "filingDate": "2021-03-19", "transactionDate": "2021-03-17", "transactionCode": "S", "transactionPrice": 655.81 }, { "name": "Baglino Andrew D", "share": 20614, "change": 1000, "filingDate": "2021-03-31", "transactionDate": "2021-03-29", "transactionCode": "M", "transactionPrice": 41.57 }, { "name": "Baglino Andrew D", "share": 19114, "change": -1500, "filingDate": "2021-03-31", "transactionDate": "2021-03-29", "transactionCode": "S", "transactionPrice": 615.75 } ], "symbol": "TSLA" }
Get insider sentiment data for US companies calculated using method discussed here. The MSPR ranges from -100 for the most negative to 100 for the most positive which can signal price changes in the coming 30-90 days.
Method: GET
Examples:
/stock/insider-sentiment?symbol=TSLA&from=2015-01-01&to=2022-03-01
Arguments:
Symbol of the company: AAPL.
From date: 2020-03-15.
To date: 2020-03-16.
Response Attributes:
Array of sentiment data.
Net buying/selling from all insiders' transactions.
Month.
Monthly share purchase ratio.
Symbol.
Year.
Symbol of the company.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.stock_insider_sentiment('AAPL', '2021-01-01', '2022-03-01'))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33
{ "data":[ { "symbol":"TSLA", "year":2021, "month":3, "change":5540, "mspr":12.209097 }, { "symbol":"TSLA", "year":2022, "month":1, "change":-1250, "mspr":-5.6179776 }, { "symbol":"TSLA", "year":2022, "month":2, "change":-1250, "mspr":-2.1459227 }, { "symbol":"TSLA", "year":2022, "month":3, "change":5870, "mspr":8.960191 } ], "symbol":"TSLA" }
Get standardized balance sheet, income statement and cash flow for global companies going back 30+ years. Data is sourced from original filings most of which made available through SEC Filings and International Filings endpoints.
Wondering why our standardized data is different from Bloomberg, Reuters, Factset, S&P or Yahoo Finance ? Check out our FAQ page to learn more
Method: GET
Premium: Premium Access Required
Examples:
/stock/financials?symbol=AAPL&statement=bs&freq=annual
/stock/financials?symbol=AC.TO&statement=ic&freq=quarterly
Arguments:
Symbol of the company: AAPL.
Statement can take 1 of these values bs, ic, cf
for Balance Sheet, Income Statement, Cash Flow respectively.
Frequency can take 1 of these values annual, quarterly, ttm, ytd
. TTM (Trailing Twelve Months) option is available for Income Statement and Cash Flow. YTD (Year To Date) option is only available for Cash Flow.
Response Attributes:
An array of map of key, value pairs containing the data for each period.
Symbol of the company.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.financials('AAPL', 'bs', 'annual'))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
{ "financials": [ { "costOfGoodsSold": 161782, "ebit": 63930, "grossIncome": 98392, "interestExpense": 3576, "netIncome": 55256, "netIncomeAfterTaxes": 55256, "period": "2019-09-28", "pretaxIncome": 65737, "provisionforIncomeTaxes": 10481, "researchDevelopment": 16217, "revenue": 260174, "sgaExpense": 18245, "totalOperatingExpense": 34462, "year": 2019 } ], "symbol": "AAPL" }
Get financials as reported. This data is available for bulk download on Kaggle SEC Financials database.
Method: GET
Examples:
/stock/financials-reported?symbol=AAPL
/stock/financials-reported?cik=320193&freq=quarterly
/stock/financials-reported?accessNumber=0000320193-20-000052
Arguments:
Symbol.
CIK.
Access number of a specific report you want to retrieve financials from.
Frequency. Can be either annual
or quarterly
. Default to annual
.
From date YYYY-MM-DD
. Filter for endDate.
To date YYYY-MM-DD
. Filter for endDate.
Response Attributes:
CIK
Array of filings.
Accepted date %Y-%m-%d %H:%M:%S
.
Access number.
CIK.
Period end date %Y-%m-%d %H:%M:%S
.
Filed date %Y-%m-%d %H:%M:%S
.
Form type.
Quarter.
Report data.
Period start date %Y-%m-%d %H:%M:%S
.
Symbol.
Year.
Symbol
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.financials_reported(symbol='AAPL', freq='annual'))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37
{ "cik": "320193", "data": [ { "accessNumber": "0000320193-19-000119", "symbol": "AAPL", "cik": "320193", "year": 2019, "quarter": 0, "form": "10-K", "startDate": "2018-09-30 00:00:00", "endDate": "2019-09-28 00:00:00", "filedDate": "2019-10-31 00:00:00", "acceptedDate": "2019-10-30 18:12:36", "report": { "bs": { "Assets": 338516000000, "Liabilities": 248028000000, "InventoryNet": 4106000000, ... }, "cf": { "NetIncomeLoss": 55256000000, "InterestPaidNet": 3423000000, ... }, "ic": { "GrossProfit": 98392000000, "NetIncomeLoss": 55256000000, "OperatingExpenses": 34462000000, ... } } } ], "symbol": "AAPL" }
Get revenue breakdown by product. This dataset is only available for US companies which disclose their revenue breakdown in the annual or quarterly reports.
Method: GET
Premium: Premium
Examples:
/stock/revenue-breakdown?symbol=AAPL
/stock/revenue-breakdown?cik=320193
Arguments:
Symbol.
CIK.
Response Attributes:
CIK
Array of revenue breakdown over multiple periods.
Access number of the report from which the data is sourced.
Revenue breakdown.
Symbol
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.stock_revenue_breakdown('AAPL'))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73
{ "cik": "320193", "data": [ { "accessNumber": "0000320193-21-000010", "breakdown": { "unit": "usd", "value": 111439000000, "concept": "us-gaap:RevenueFromContractWithCustomerExcludingAssessedTax", "endDate": "2020-12-26", "startDate": "2020-09-27", "revenueBreakdown": [ { "axis": "srt:ProductOrServiceAxis", "data": [ { "unit": "usd", "label": "Products", "value": 95678000000, "member": "us-gaap:ProductMember", "percentage": 85.85683647556061 }, { "unit": "usd", "label": "Services", "value": 15761000000, "member": "us-gaap:ServiceMember", "percentage": 14.14316352443938 }, { "unit": "usd", "label": "Services", "value": 15761000000, "member": "us-gaap:ServiceMember", "percentage": 14.14316352443938 }, { "unit": "usd", "label": "iPhone", "value": 65597000000, "member": "aapl:IPhoneMember", "percentage": 58.86359353547681 }, { "unit": "usd", "label": "Mac", "value": 8675000000, "member": "aapl:MacMember", "percentage": 7.784527858290185 }, { "unit": "usd", "label": "iPad", "value": 8435000000, "member": "aapl:IPadMember", "percentage": 7.569163398810111 }, { "unit": "usd", "label": "Wearables, Home and Accessories", "value": 12971000000, "member": "aapl:WearablesHomeandAccessoriesMember", "percentage": 11.639551682983516 } ], "label": "Product and Service [Axis]" }, ] } } ], "symbol": "AAPL" }
List company's filing. Limit to 250 documents at a time. This data is available for bulk download on Kaggle SEC Filings database.
Method: GET
Examples:
/stock/filings?accessNumber=0000320193-20-000052
Arguments:
Symbol. Leave symbol
,cik
and accessNumber
empty to list latest filings.
CIK.
Access number of a specific report you want to retrieve data from.
Filter by form. You can use this value NT 10-K
to find non-timely filings for a company.
From date: 2023-03-15.
To date: 2023-03-16.
Response Attributes:
Accepted date %Y-%m-%d %H:%M:%S
.
Access number.
CIK.
Filed date %Y-%m-%d %H:%M:%S
.
Filing's URL.
Form type.
Report's URL.
Symbol.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.filings(symbol='AAPL', _from="2020-01-01", to="2020-06-11"))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
[ { "accessNumber": "0001193125-20-050884", "symbol": "AAPL", "cik": "320193", "form": "8-K", "filedDate": "2020-02-27 00:00:00", "acceptedDate": "2020-02-27 06:14:21", "reportUrl": "https://www.sec.gov/ix?doc=/Archives/edgar/data/320193/000119312520050884/d865740d8k.htm", "filingUrl": "https://www.sec.gov/Archives/edgar/data/320193/000119312520050884/0001193125-20-050884-index.html" }, { "accessNumber": "0001193125-20-039203", "symbol": "AAPL", "cik": "320193", "form": "8-K", "filedDate": "2020-02-18 00:00:00", "acceptedDate": "2020-02-18 06:24:57", "reportUrl": "https://www.sec.gov/ix?doc=/Archives/edgar/data/320193/000119312520039203/d845033d8k.htm", "filingUrl": "https://www.sec.gov/Archives/edgar/data/320193/000119312520039203/0001193125-20-039203-index.html" }, ... ]
Get sentiment analysis of 10-K and 10-Q filings from SEC. An abnormal increase in the number of positive/negative words in filings can signal a significant change in the company's stock price in the upcoming 4 quarters. We make use of Loughran and McDonald Sentiment Word Lists to calculate the sentiment for each filing.
Method: GET
Premium: Premium Access Required
Examples:
/stock/filings-sentiment?accessNumber=0000320193-20-000052
Arguments:
Access number of a specific report you want to retrieve data from.
Response Attributes:
Access number.
CIK.
Filing Sentiment
% of constraining words in the filing.
% of litigious words in the filing.
% of modal-moderate words in the filing.
% of modal-strong words in the filing.
% of modal-weak words in the filing.
% of negative words in the filing.
% of polarity words in the filing.
% of positive words in the filing.
% of uncertainty words in the filing.
Symbol.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.sec_sentiment_analysis('0000320193-20-000052'))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
{ "cik": "320193", "symbol": "AAPL", "accessNumber": "0000320193-20-000052", "sentiment": { "negative": 1.2698412698412698, "polarity": -0.1147540479911535, "positive": 0.5042016806722689, "litigious": 0.2427637721755369, "modal-weak": 0.392156862745098, "uncertainty": 1.1391223155929038, "constraining": 0.5975723622782446, "modal-strong": 0.14939309056956115, "modal-moderate": 0.11204481792717086 } }
Calculate the textual difference between a company's 10-K / 10-Q reports and the same type of report in the previous year using Cosine Similarity. For example, this endpoint compares 2019's 10-K with 2018's 10-K. Companies breaking from its routines in disclosure of financial condition and risk analysis section can signal a significant change in the company's stock price in the upcoming 4 quarters.
Method: GET
Premium: Premium Access Required
Examples:
/stock/similarity-index?symbol=AAPL&freq=annual
/stock/similarity-index?cik=320193&freq=quarterly
Arguments:
Symbol. Required if cik is empty
CIK. Required if symbol is empty
annual
or quarterly
. Default to annual
Response Attributes:
CIK.
Array of filings with its cosine similarity compared to the same report of the previous year.
Accepted date %Y-%m-%d %H:%M:%S
.
Access number.
CIK.
Filed date %Y-%m-%d %H:%M:%S
.
Filing's URL.
Form type.
Cosine similarity of Item 1 (Business). This number is only available for Annual reports.
Cosine similarity of Item 1A (Risk Factors). This number is available for both Annual and Quarterly reports.
Cosine similarity of Item 2 (Management’s Discussion and Analysis of Financial Condition and Results of Operations). This number is only available for Quarterly reports.
Cosine similarity of Item 7 (Management’s Discussion and Analysis of Financial Condition and Results of Operations). This number is only available for Annual reports.
Cosine similarity of Item 7A (Quantitative and Qualitative Disclosures About Market Risk). This number is only available for Annual reports.
Report's URL.
Symbol.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.sec_similarity_index('AAPL'))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34
{ "cik": "320193", "similarity": [ { "cik": "320193", "accessNumber": "0000320193-19-000119", "item1": 0.8833750347608914, "item2": 0, "item1a": 0.994836154829746, "item7": 0.897030072745, "item7a": 0.9843052590436008, "form": "10-K", "reportUrl": "https://www.sec.gov/ix?doc=/Archives/edgar/data/320193/000032019319000119/a10-k20199282019.htm", "filingUrl": "https://www.sec.gov/Archives/edgar/data/320193/000032019319000119/0000320193-19-000119-index.html", "filedDate": "2019-10-31 00:00:00", "acceptedDate": "2019-10-30 18:12:36" }, { "cik": "320193", "accessNumber": "0000320193-18-000145", "item1": 0.9737784696339462, "item2": 0, "item1a": 0.9931651573630014, "item7": 0.9441063774798184, "item7a": 0.9856181212005336, "form": "10-K", "reportUrl": "https://www.sec.gov/Archives/edgar/data/320193/000032019318000145/a10-k20189292018.htm", "filingUrl": "https://www.sec.gov/Archives/edgar/data/320193/000032019318000145/0000320193-18-000145-index.html", "filedDate": "2018-11-05 00:00:00", "acceptedDate": "2018-11-05 08:01:40" } ], "symbol": "AAPL" }
Get recent and upcoming IPO.
Method: GET
Examples:
/calendar/ipo?from=2020-01-01&to=2020-04-30
Arguments:
From date: 2020-03-15.
To date: 2020-03-16.
Response Attributes:
Array of IPO events.
IPO date.
Exchange.
Company's name.
Number of shares offered during the IPO.
Projected price or price range.
IPO status. Can take 1 of the following values: expected
,priced
,withdrawn
,filed
Symbol.
Total shares value.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.ipo_calendar(_from="2020-05-01", to="2020-06-01"))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24
{ "ipoCalendar": [ { "date": "2020-04-03", "exchange": "NASDAQ Global", "name": "ZENTALIS PHARMACEUTICALS, LLC", "numberOfShares": 7650000, "price": "16.00-18.00", "status": "expected", "symbol": "ZNTL", "totalSharesValue": 158355000 }, { "date": "2020-04-01", "exchange": "NASDAQ Global", "name": "WIMI HOLOGRAM CLOUD INC.", "numberOfShares": 5000000, "price": "5.50-7.50", "status": "expected", "symbol": "WIMI", "totalSharesValue": 43125000 }, ] }
Get dividends data for common stocks going back 30 years.
Method: GET
Premium: Premium Access Required
Examples:
/stock/dividend?symbol=AAPL&from=2022-02-01&to=2023-02-01
Arguments:
Symbol.
YYYY-MM-DD.
YYYY-MM-DD.
Response Attributes:
Adjusted dividend.
Amount in local currency.
Currency.
Ex-Dividend date.
Declaration date.
Dividend frequency. Can be 1 of the following values:
0: Annually
1: Monthly
2: Quarterly
3: Semi-annually
4: Other/Unknown
5: Bimonthly
6: Trimesterly
7: Weekly
Pay date.
Record date.
Symbol.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.stock_dividends('KO', _from='2019-01-01', to='2020-01-01'))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42
[ { "symbol": "AAPL", "date": "2019-11-07", "amount": 0.77, "adjustedAmount": 0.77, "payDate": "2019-11-14", "recordDate": "2019-11-11", "declarationDate": "2019-10-30", "currency": "USD" }, { "symbol": "AAPL", "date": "2019-08-09", "amount": 0.77, "adjustedAmount": 0.77, "payDate": "2019-08-15", "recordDate": "2019-08-12", "declarationDate": "2019-07-30", "currency": "USD" }, { "symbol": "AAPL", "date": "2019-05-10", "amount": 0.77, "adjustedAmount": 0.77, "payDate": "2019-05-16", "recordDate": "2019-05-13", "declarationDate": "2019-05-01", "currency": "USD" }, { "symbol": "AAPL", "date": "2019-02-08", "amount": 0.73, "adjustedAmount": 0.77, "payDate": "2019-02-14", "recordDate": "2019-02-11", "declarationDate": "2019-01-29", "currency": "USD" } ]
Get ratios for different sectors and regions/indices.
Method: GET
Premium: Premium Access Required
Examples:
Arguments:
Region. A list of supported values for this field can be found here.
Response Attributes:
Metrics for each sector.
Metrics data in key-value format. a
and m
fields are for average and median respectively.
Sector
Region.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.sector_metric('NA'))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
{ "data": [ { "metrics": { "assetTurnoverAnnual": { "a": 0.7245, "m": 0.5426 }, "assetTurnoverTTM": { "a": 0.7254, "m": 0.5463 }, }, "sector": "Communication Services" }, { "metrics": { "currentDividendYieldTTM": { "a": 30.9763, "m": 2.09 }, "currentEv/freeCashFlowAnnual": { "a": 286.4793, "m": 19.8488 }, }, "sector": "Consumer Discretionary" } ], "region": "Asia_Ocenia" }
Get company price performance statistics such as 52-week high/low, YTD return and much more.
Method: GET
Premium: Premium Access Required
Examples:
/stock/price-metric?symbol=AAPL
Arguments:
Symbol of the company: AAPL.
Get data on a specific date in the past. The data is available weekly so your date will be automatically adjusted to the last day of that week.
Response Attributes:
Data date.
Map key-value pair of key ratios and metrics.
Symbol of the company.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.price_metrics('AAPL'))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
{ "data": { "100DayEMA": 295.7694, "100DaySMA": 319.2297, "10DayAverageTradingVolume": 53717320, "10DayEMA": 247.4641, "10DaySMA": 247.372, "14DayRSI": 34.0517, "1MonthHigh": 314.67, "1MonthHighDate": "2022-08-16", "50DayEMA": 277.482, "50DaySMA": 288.313, "52WeekHigh": 414.5, "52WeekHighDate": "2021-11-04", "52WeekLow": 206.86, "52WeekLowDate": "2022-05-24", "5DayEMA": 245.8814, "ytdPriceReturn": 10.1819 }, "symbol": "TSLA" }
Get a list of symbol changes for US-listed, EU-listed, NSE and ASX securities. Limit to 2000 events at a time.
Method: GET
Premium: Premium Access Required
Examples:
/ca/symbol-change?from=2022-09-01&to=2022-10-30
Arguments:
From date YYYY-MM-DD
.
To date YYYY-MM-DD
.
Response Attributes:
Array of symbol change events.
Event's date.
New symbol.
Old symbol.
From date.
To date.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.symbol_change(_from="2022-10-01", to="2022-10-11"))
1 2 3 4 5 6 7 8 9 10 11
{ "data": [ { "atDate": "2022-10-05", "newSymbol": "MEN.L", "oldSymbol": "PPC.L" } ], "fromDate": "2022-10-01", "toDate": "2022-10-30" }
Get a list of ISIN changes for EU-listed securities. Limit to 2000 events at a time.
Method: GET
Premium: Premium Access Required
Examples:
/ca/isin-change?from=2022-09-01&to=2022-10-30
Arguments:
From date YYYY-MM-DD
.
To date YYYY-MM-DD
.
Response Attributes:
Array of ISIN change events.
Event's date.
New ISIN.
Old ISIN.
From date.
To date.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.isin_change(_from="2022-10-01", to="2022-10-11"))
1 2 3 4 5 6 7 8 9 10 11
{ "data": [ { "atDate": "2021-08-30", "newIsin": "DE000A3E5CP0", "oldIsin": "DE0007239402" } ], "fromDate": "2021-08-07", "toDate": "2021-10-07" }
Get historical market cap data for global companies.
Method: GET
Premium: Accessible with Fundamental 2 or All in One subscription.
Examples:
/stock/historical-market-cap?symbol=AAPL&from=2022-01-01&to=2024-05-06
Arguments:
Company symbol.
From date YYYY-MM-DD
.
To date YYYY-MM-DD
.
Response Attributes:
Currency
Array of market data.
Date of the reading
Value
Symbol
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.historical_market_cap('AAPL', _from="2020-06-01", to="2020-06-10"))
1 2 3 4 5 6 7 8 9 10 11 12 13 14
{ "currency": "USD", "data": [ { "atDate": "2024-06-10", "marketCapitalization": 3759.182 }, { "atDate": "2024-06-09", "marketCapitalization": 21508.447 } ], "symbol": "SYM" }
Get historical employee count for global companies.
Method: GET
Premium: Accessible with Fundamental 2 or All in One subscription.
Examples:
/stock/historical-employee-count?symbol=AAPL&from=2022-01-01&to=2024-05-06
Arguments:
Company symbol.
From date YYYY-MM-DD
.
To date YYYY-MM-DD
.
Response Attributes:
Array of market data.
Date of the reading
Value
Symbol
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.historical_employee_count('AAPL', _from="2020-06-01", to="2020-06-10"))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
{ "data": [ { "atDate": "2023-09-30", "employee": 161000 }, { "atDate": "2022-09-24", "employee": 164000 }, { "atDate": "2021-09-25", "employee": 154000 }, { "atDate": "2020-09-26", "employee": 147000 } ], "symbol": "AAPL" }
Get latest analyst recommendation trends for a company.
Method: GET
Examples:
/stock/recommendation?symbol=AAPL
/stock/recommendation?symbol=TSLA
Arguments:
Symbol of the company: AAPL.
Response Attributes:
Number of recommendations that fall into the Buy category
Number of recommendations that fall into the Hold category
Updated period
Number of recommendations that fall into the Sell category
Number of recommendations that fall into the Strong Buy category
Number of recommendations that fall into the Strong Sell category
Company symbol.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.recommendation_trends('AAPL'))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20
[ { "buy": 24, "hold": 7, "period": "2020-03-01", "sell": 0, "strongBuy": 13, "strongSell": 0, "symbol": "AAPL" }, { "buy": 17, "hold": 13, "period": "2020-02-01", "sell": 5, "strongBuy": 13, "strongSell": 0, "symbol": "AAPL" } ]
Get latest price target consensus.
Method: GET
Premium: Premium required.
Examples:
/stock/price-target?symbol=NFLX
/stock/price-target?symbol=DIS
Arguments:
Symbol of the company: AAPL.
Response Attributes:
Updated time of the data
Number of Analysts.
Company symbol.
Highes analysts' target.
Lowest analysts' target.
Mean of all analysts' targets.
Median of all analysts' targets.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.price_target('AAPL'))
1 2 3 4 5 6 7 8 9
{ "lastUpdated": "2023-04-06 00:00:00", "numberAnalysts": 39, "symbol": "NFLX", "targetHigh": 462, "targetLow": 217.15, "targetMean": 364.37, "targetMedian": 359.04 }
Get latest stock upgrade and downgrade.
Method: GET
Premium: Premium Access Required
Examples:
/stock/upgrade-downgrade?symbol=AAPL
/stock/upgrade-downgrade?symbol=BYND
Arguments:
Symbol of the company: AAPL. If left blank, the API will return latest stock upgrades/downgrades.
From date: 2000-03-15.
To date: 2020-03-16.
Response Attributes:
Action can take any of the following values: up(upgrade), down(downgrade), main(maintains), init(initiate), reit(reiterate)
.
Company/analyst who did the upgrade/downgrade.
From grade.
Upgrade/downgrade time in UNIX timestamp.
Company symbol.
To grade.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.upgrade_downgrade(symbol='AAPL', _from='2020-01-01', to='2020-06-30'))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26
[ { "symbol": "BYND", "gradeTime": 1567728000, "company": "DA Davidson", "fromGrade": "", "toGrade": "Underperform", "action": "init" }, { "symbol": "BYND", "gradeTime": 1566259200, "company": "JP Morgan", "fromGrade": "Neutral", "toGrade": "Overweight", "action": "up" }, { "symbol": "BYND", "gradeTime": 1564704000, "company": "Bank of America", "fromGrade": "", "toGrade": "Neutral", "action": "reit" } ]
Get company's revenue estimates.
Method: GET
Premium: Premium Access Required
Examples:
/stock/revenue-estimate?symbol=AAPL
/stock/revenue-estimate?symbol=TSLA&freq=annual
Arguments:
Symbol of the company: AAPL.
Can take 1 of the following values: annual, quarterly
. Default to quarterly
Response Attributes:
List of estimates
Number of Analysts.
Period.
Fiscal quarter.
Average revenue estimates including Finnhub's proprietary estimates.
Highest estimate.
Lowest estimate.
Fiscal year.
Frequency: annual or quarterly.
Company symbol.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.company_revenue_estimates('TSLA', freq='quarterly'))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24
{ "data": [ { "numberAnalysts": 31, "period": "2020-06-30", "revenueAvg": 58800500000, "revenueHigh": 64060000000, "revenueLow": 54072000000, "quarter": 3, "year": 2020 }, { "numberAnalysts": 31, "period": "2020-03-31", "revenueAvg": 61287300000, "revenueHigh": 66557000000, "revenueLow": 54871000000, "quarter": 2, "year": 2020 } ], "freq": "quarterly", "symbol": "AAPL" }
Get company's EPS estimates.
Method: GET
Premium: Premium Access Required
Examples:
/stock/eps-estimate?symbol=AAPL
/stock/eps-estimate?symbol=AMZN&freq=annual
Arguments:
Symbol of the company: AAPL.
Can take 1 of the following values: annual, quarterly
. Default to quarterly
Response Attributes:
List of estimates
Average EPS estimates including Finnhub's proprietary estimates.
Highest estimate.
Lowest estimate.
Number of Analysts.
Period.
Fiscal quarter.
Fiscal year.
Frequency: annual or quarterly.
Company symbol.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.company_eps_estimates('AAPL', freq='quarterly'))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24
{ "data": [ { "epsAvg": 2.65, "epsHigh": 2.98, "epsLow": 2.05, "numberAnalysts": 35, "period": "2020-06-30", "quarter": 3, "year": 2020 }, { "epsAvg": 2.52, "epsHigh": 3.02, "epsLow": 2.21, "numberAnalysts": 34, "period": "2020-03-31", "quarter": 2, "year": 2020 } ], "freq": "quarterly", "symbol": "AAPL" }
Get company's ebitda estimates.
Method: GET
Premium: Premium Access Required
Examples:
/stock/ebitda-estimate?symbol=AAPL
/stock/ebitda-estimate?symbol=TSLA&freq=annual
Arguments:
Symbol of the company: AAPL.
Can take 1 of the following values: annual, quarterly
. Default to quarterly
Response Attributes:
List of estimates
Average EBITDA estimates including Finnhub's proprietary estimates.
Highest estimate.
Lowest estimate.
Number of Analysts.
Period.
Fiscal quarter.
Fiscal year.
Frequency: annual or quarterly.
Company symbol.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.company_ebitda_estimates('TSLA', freq='quarterly'))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24
{ "data": [ { "numberAnalysts": 31, "period": "2020-06-30", "ebitdaAvg": 58800500000, "ebitdaHigh": 64060000000, "ebitdaLow": 54072000000, "quarter": 3, "year": 2020 }, { "numberAnalysts": 31, "period": "2020-03-31", "ebitdaAvg": 61287300000, "ebitdaHigh": 66557000000, "ebitdaLow": 54871000000, "quarter": 2, "year": 2020 } ], "freq": "quarterly", "symbol": "AAPL" }
Get company's ebit estimates.
Method: GET
Premium: Premium Access Required
Examples:
/stock/ebit-estimate?symbol=AAPL
/stock/ebit-estimate?symbol=TSLA&freq=annual
Arguments:
Symbol of the company: AAPL.
Can take 1 of the following values: annual, quarterly
. Default to quarterly
Response Attributes:
List of estimates
Average EBIT estimates including Finnhub's proprietary estimates.
Highest estimate.
Lowest estimate.
Number of Analysts.
Period.
Fiscal quarter.
Fiscal year.
Frequency: annual or quarterly.
Company symbol.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.company_ebit_estimates('TSLA', freq='quarterly'))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24
{ "data": [ { "numberAnalysts": 31, "period": "2020-06-30", "ebitAvg": 58800500000, "ebitHigh": 64060000000, "ebitLow": 54072000000 "quarter": 3, "year": 2020, }, { "numberAnalysts": 31, "period": "2020-03-31", "ebitAvg": 61287300000, "ebitHigh": 66557000000, "ebitLow": 54871000000, "quarter": 2, "year": 2020, } ], "freq": "quarterly", "symbol": "AAPL" }
Get company historical quarterly earnings surprise going back to 2000.
Method: GET
Free Tier: Last 4 quarters
Examples:
Arguments:
Symbol of the company: AAPL.
Limit number of period returned. Leave blank to get the full history.
Response Attributes:
Actual earning result.
Estimated earning.
Reported period.
Fiscal quarter.
Surprise - The difference between actual and estimate.
Surprise percent.
Company symbol.
Fiscal year.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.company_earnings('TSLA', limit=5))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32
[ { "actual": 1.88, "estimate": 1.9744, "period": "2023-03-31", "quarter": 1, "surprise": -0.0944, "surprisePercent": -4.7812, "symbol": "AAPL", "year": 2023 }, { "actual": 1.29, "estimate": 1.2957, "period": "2022-12-31", "quarter": 4, "surprise": -0.0057, "surprisePercent": -0.4399, "symbol": "AAPL", "year": 2022 }, { "actual": 1.2, "estimate": 1.1855, "period": "2022-09-30", "quarter": 3, "surprise": 0.0145, "surprisePercent": 1.2231, "symbol": "AAPL", "year": 2022 } ]
Get historical and coming earnings release. EPS and Revenue in this endpoint are non-GAAP, which means they are adjusted to exclude some one-time or unusual items. This is the same data investors usually react to and talked about on the media. Estimates are sourced from both sell-side and buy-side analysts.
Method: GET
Free Tier: 1 month of historical earnings and new updates
Examples:
/calendar/earnings?from=2023-03-01&to=2023-03-10
/calendar/earnings?from=2022-03-01&to=2023-03-09&symbol=AAPL
Arguments:
From date: 2020-03-15.
To date: 2020-03-16.
Filter by symbol: AAPL.
Set to true
to include international markets. Default value is false
Response Attributes:
Array of earnings release.
Date.
EPS actual.
EPS estimate.
Indicates whether the earnings is announced before market open(bmo
), after market close(amc
), or during market hour(dmh
).
Earnings quarter.
Revenue actual.
Revenue estimate including Finnhub's proprietary estimates.
Symbol.
Earnings year.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.earnings_calendar(_from="2021-06-10", to="2021-06-30", symbol="", international=False))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26
{ "earningsCalendar": [ { "date": "2020-01-28", "epsActual": 4.99, "epsEstimate": 4.5474, "hour": "amc", "quarter": 1, "revenueActual": 91819000000, "revenueEstimate": 88496400810, "symbol": "AAPL", "year": 2020 }, { "date": "2019-10-30", "epsActual": 3.03, "epsEstimate": 2.8393, "hour": "amc", "quarter": 4, "revenueActual": 64040000000, "revenueEstimate": 62985161760, "symbol": "AAPL", "year": 2019 } ] }
Get real-time quote data for US stocks. Constant polling is not recommended. Use websocket if you need real-time updates.
Real-time stock prices for international markets are supported for Enterprise clients via our partner's feed. Contact Us to learn more.
Method: GET
Examples:
Arguments:
Symbol
Response Attributes:
Current price
Change
Percent change
High price of the day
Low price of the day
Open price of the day
Previous close price
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.quote('AAPL'))
1 2 3 4 5 6 7 8
{ "c": 261.74, "h": 263.31, "l": 260.68, "o": 261.07, "pc": 259.45, "t": 1582641000 }
Get candlestick data (OHLCV) for stocks.
Daily data will be adjusted for Splits. Intraday data will remain unadjusted. Only 1 month of intraday will be returned at a time. If you need more historical intraday data, please use the from and to params iteratively to request more data.
Method: GET
Premium: Premium Access Required
Examples:
/stock/candle?symbol=AAPL&resolution=1&from=1693493346&to=1693752546
/stock/candle?symbol=IBM&resolution=D&from=1572651390&to=1575243390
Arguments:
Symbol.
Supported resolution includes 1, 5, 15, 30, 60, D, W, M
.Some timeframes might not be available depending on the exchange.
UNIX timestamp. Interval initial value.
UNIX timestamp. Interval end value.
Response Attributes:
List of close prices for returned candles.
List of high prices for returned candles.
List of low prices for returned candles.
List of open prices for returned candles.
Status of the response. This field can either be ok or no_data.
List of timestamp for returned candles.
List of volume data for returned candles.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.stock_candles('AAPL', 'D', 1590988249, 1591852249))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33
{ "c": [ 217.68, 221.03, 219.89 ], "h": [ 222.49, 221.5, 220.94 ], "l": [ 217.19, 217.1402, 218.83 ], "o": [ 221.03, 218.55, 220 ], "s": "ok", "t": [ 1569297600, 1569384000, 1569470400 ], "v": [ 33463820, 24018876, 20730608 ] }
Get historical tick data for global exchanges.
For more historical tick data, you can visit our bulk download page in the Dashboard here to speed up the download process.
Exchange | Segment | Delay |
---|---|---|
US CTA/UTP | Full SIP | End-of-day |
TSX |
|
End-of-day |
LSE |
|
15 minute |
Euronext |
|
End-of-day |
Deutsche Börse |
|
End-of-day |
Method: GET
Premium: Premium Access Required
Examples:
/stock/tick?symbol=AAPL&date=2021-03-09&limit=500&skip=0&format=json
/stock/tick?symbol=AC.TO&date=2021-03-09&limit=500&skip=0&format=json
/stock/tick?symbol=BARC.L&date=2021-03-09&limit=500&skip=0&format=json
Arguments:
Symbol.
Date: 2020-04-02.
Limit number of ticks returned. Maximum value: 25000
Number of ticks to skip. Use this parameter to loop through the entire data.
Response Attributes:
List of trade conditions. A comprehensive list of trade conditions code can be found here
Number of ticks returned. If count
< limit
, all data for that date has been returned.
List of price data.
Symbol.
Number of ticks skipped.
List of timestamp in UNIX ms.
Total number of ticks for that date.
List of volume data.
List of venues/exchanges. A list of exchange codes can be found here
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.stock_tick('AAPL', '2020-03-25', 500, 0))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26
{ "p": [ 255, 255, 255 ], "s": "AAPL", "skip": 0, "t": [ 1585108800073, 1585108800315, 1585108800381 ], "v": [ 2513, 24, 1 ], "x": [ "P", "P", "P" ], "count": 3, "c":[["1","24"],["1","24","12"],["1","24","12"]] }
Get historical best bid and offer for US stocks, LSE, TSX, Euronext and Deutsche Borse.
For US market, this endpoint only serves historical NBBO from the beginning of 2020. To download more historical data, please visit our bulk download page in the Dashboard here.
Method: GET
Premium: Premium Access Required
Examples:
/stock/bbo?symbol=AAPL&date=2021-03-09&limit=500&skip=0&format=json
/stock/bbo?symbol=AC.TO&date=2021-03-09&limit=500&skip=0&format=json
/stock/bbo?symbol=BARC.L&date=2021-03-09&limit=500&skip=0&format=json
Arguments:
Symbol.
Date: 2020-04-02.
Limit number of ticks returned. Maximum value: 25000
Number of ticks to skip. Use this parameter to loop through the entire data.
Response Attributes:
List of Ask price data.
List of Ask volume data.
List of venues/exchanges - Ask price. A list of exchange codes can be found here
List of Bid price data.
List of Bid volume data.
List of venues/exchanges - Bid price. A list of exchange codes can be found here
List of quote conditions. A comprehensive list of quote conditions code can be found here
Number of ticks returned. If count
< limit
, all data for that date has been returned.
Symbol.
Number of ticks skipped.
List of timestamp in UNIX ms.
Total number of ticks for that date.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.stock_nbbo('AAPL', '2020-03-25', 500, 0))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52
{ "a": [ 137, 133.2, 126.08 ], "av": [ 1, 2, 1 ], "ax": [ "P", "P", "P" ], "b": [ 116.5, 116.5, 116.5 ], "bv": [ 1, 1, 1 ], "bx": [ "P", "P", "P" ], "c": [ [ "1" ], [ "1" ], [ "1" ] ], "count": 3, "s": "AAPL", "skip": 5, "t": [ 1615280400047, 1615280400047, 1615280400047 ], "total": 2739880 }
Get last bid/ask data for US stocks.
Method: GET
Premium: Premium Access Required
Examples:
Arguments:
Symbol.
Response Attributes:
Ask price.
Ask volume.
Bid price.
Bid volume.
Reference UNIX timestamp in ms.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.last_bid_ask('AAPL'))
1 2 3 4 5 6 7
{ "a": 338.65, "av": 2, "b": 338.61, "bv": 2, "t": 1591995678874 }
Get splits data for stocks.
Method: GET
Premium: Premium required.
Examples:
/stock/split?symbol=AAPL&from=2015-02-01&to=2021-03-09
Arguments:
Symbol.
YYYY-MM-DD.
YYYY-MM-DD.
Response Attributes:
Split date.
From factor.
Symbol.
To factor.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.stock_splits('AAPL', _from='2000-01-01', to='2020-01-01'))
1 2 3 4 5 6 7 8
[ { "symbol": "AAPL", "date": "2014-06-09", "fromFactor": 1, "toFactor": 7 } ]
Get global dividends data.
Method: GET
Premium: Premium required.
Examples:
Arguments:
Symbol.
Response Attributes:
Amount in local currency.
Ex-Dividend date.
Symbol
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.stock_basic_dividends('AAPL'))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
{ "data": [ { "exDate": "2019-11-07", "amount": 0.77, }, { "exDate": "2019-08-09", "amount": 0.77, }, { "exDate": "2019-05-10", "amount": 0.77, } ], "symbol": "AAPL" }
Get a list of index's constituents. A list of supported indices for this endpoint can be found here.
Method: GET
Premium: Premium Access Required
Examples:
/index/constituents?symbol=^GSPC
/index/constituents?symbol=^FTSE
Arguments:
symbol
Response Attributes:
Array of constituents.
Array of constituents' details.
Cusip.
ISIN.
Name.
Global Share Class FIGI.
Symbol.
Weight.
Index's symbol.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.indices_const(symbol = "^GSPC"))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25
{ "constituents": [ "AAPL", "MSFT" ], "constituentsBreakdown": [ { "cusip": "037833100", "isin": "US0378331005", "name": "Apple Inc", "shareClassFIGI": "BBG001S5N8V8", "symbol": "AAPL", "weight": 7.03049 }, { "cusip": "594918104", "isin": "US5949181045", "name": "Microsoft Corp", "shareClassFIGI": "BBG001S5TD05", "symbol": "MSFT", "weight": 6.3839 } ], "symbol": "^GSPC" }
Get full history of index's constituents including symbols and dates of joining and leaving the Index. Currently support ^GSPC
, ^NDX
, ^DJI
Method: GET
Premium: Premium required.
Examples:
/index/historical-constituents?symbol=^GSPC
/index/historical-constituents?symbol=^NDX
Arguments:
symbol
Response Attributes:
Array of historical constituents.
add
or remove
.
Date of joining or leaving the index.
Symbol
Index's symbol.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.indices_hist_const(symbol = "^GSPC"))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20
{ "historicalConstituents": [ { "action": "add", "symbol": "TYL", "date": "2020-06-22" }, { "action": "add", "symbol": "TDY", "date": "2020-06-22" }, { "action": "remove", "symbol": "JWN", "date": "2020-06-22" } ], "symbol": "^GSPC" }
Get ETF profile information. This endpoint has global coverage. A list of supported ETFs can be found here.
Method: GET
Premium: Premium required.
Examples:
/etf/profile?isin=US78462F1030
Arguments:
ETF symbol.
ETF isin.
Response Attributes:
Profile data.
Asset Class.
AUM.
30-day average volume.
CUSIP.
ETF's description.
ETF domicile.
ETF issuer.
Expense ratio. For non-US funds, this is the KID ongoing charges.
Inception date.
Investment Segment.
Whether the ETF is inverse
Whether the ETF is leveraged
ISIN.
Leverage factor.
Logo.
Name
NAV.
NAV currency.
P/B.
P/E.
Tracking Index.
ETF's website.
Symbol.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.etfs_profile('SPY'))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24
{ "profile": { "assetClass": "Equity", "aum": 318374000000, "avgVolume": 63794600, "cusip": "", "description": "SPY was created on 1993-01-22 by SPDR. The fund's investment portfolio concentrates primarily on large cap equity. The ETF currently has 318374.0m in AUM and 504 holdings. SPY tracks a market-cap-weighted index of US large- and midcap stocks selected by the S\u0026P Committee.", "domicile": "US", "etfCompany": "SPDR", "expenseRatio": 0.0945, "inceptionDate": "1993-01-22", "investmentSegment": "Large Cap", "isin": "", "name": "SPDR S\u0026P 500 ETF Trust", "nav": 366.2784, "navCurrency": "USD", "priceToBook": 3.943968, "priceToEarnings": 26.82968, "trackingIndex": "S\u0026P 500", "logo": "https://static2.finnhub.io/file/publicdatany/finnhubimage/etf_logo/spdr.png", "website": "https://us.spdrs.com/en/etf/spdr-sp-500-etf-SPY" }, "symbol": "SPY" }
Get full ETF holdings/constituents. This endpoint has global coverage. Widget only shows top 10 holdings. A list of supported ETFs can be found here.
Method: GET
Premium: Premium required.
Examples:
/etf/holdings?symbol=SPY&skip=1
/etf/holdings?symbol=IPO&date=2022-03-10
Arguments:
ETF symbol.
ETF isin.
Skip the first n results. You can use this parameter to query historical constituents data. The latest result is returned if skip=0 or not set.
Query holdings by date. You can use either this param or skip
param, not both.
Response Attributes:
Holdings update date.
Array of holdings.
Asset type. Can be 1 of the following values: Equity
, ETP
, Fund
, Bond
, Other
or empty.
CUSIP.
ISIN.
Security name
Portfolio's percent
Number of shares owned by the ETF.
Symbol description
Market value
Number of holdings.
ETF symbol.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.etfs_holdings('SPY'))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27
{ "atDate": "2023-03-24", "holdings": [ { "assetType": "Equity", "cusip": "88160R101", "isin": "US88160R1014", "name": "TESLA INC", "percent": 10.54, "share": 3971395, "symbol": "TSLA", "value": 763381546.9 }, { "assetType": "Equity", "cusip": "98980L101", "isin": "US98980L1017", "name": "ZOOM VIDEO COMMUNICATIONS-A", "percent": 8.05, "share": 8418916, "symbol": "ZM", "value": 582504798.04 }, ], "numberOfHoldings": 28, "symbol": "ARKK" }
Get ETF sector exposure data.
Method: GET
Premium: Premium Access Required
Examples:
Arguments:
ETF symbol.
ETF isin.
Response Attributes:
Array of industries and exposure levels.
Percent of exposure.
Industry
ETF symbol.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.etfs_sector_exp('SPY'))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
{ "sectorExposure": [ { "exposure": 31.96, "industry": "Technology" }, { "exposure": 14.79, "industry": "Healthcare" }, { "exposure": 13.46, "industry": "Consumer Cyclicals" } ], "symbol": "SPY" }
Get ETF country exposure data.
Method: GET
Premium: Premium Access Required
Examples:
Arguments:
ETF symbol.
ETF isin.
Response Attributes:
Array of countries and and exposure levels.
Country
Percent of exposure.
ETF symbol.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.etfs_country_exp('SPY'))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25
{ "countryExposure": [ { "country": "United States of America (the)", "exposure": 97.02 }, { "country": "Ireland", "exposure": 1.65 }, { "country": "United Kingdom of Great Britain and Northern Ireland (the)", "exposure": 0.88 }, { "country": "Switzerland", "exposure": 0.41 }, { "country": "Bermuda", "exposure": 0.03 } ], "symbol": "SPY" }
Get mutual funds profile information. This endpoint covers both US and global mutual funds. For international funds, you must query the data using ISIN. A list of supported funds can be found here.
Method: GET
Premium: Premium required.
Examples:
/mutual-fund/profile?symbol=VTSAX
/mutual-fund/profile?isin=US9229087286
/mutual-fund/profile?isin=LU1748855837
Arguments:
Fund's symbol.
Fund's isin.
Response Attributes:
Profile data.
Index benchmark.
Beta.
Fund's category.
Class ID.
Class name.
Fund's currency
CUSIP.
Deferred load.
Fund's description.
Expense ratio.
12B-1 fee.
Front Load.
Fund Company.
Fund Family.
Inception date.
Investment Segment.
IRA minimum investment.
ISIN.
Fund's managers.
Max redemption fee.
Name
Fund's series ID. This field can be used to group multiple share classes into 1 unique fund.
Fund's series name.
SFDR classification for EU funds. Under the new classifications, a fund's strategy will labeled under either Article 6, 8 or 9. Article 6 covers funds which do not integrate any kind of sustainability into the investment process. Article 8, also known as ‘environmental and socially promoting’, applies “… where a financial product promotes, among other characteristics, environmental or social characteristics, or a combination of those characteristics, provided that the companies in which the investments are made follow good governance practices.”. Article 9, also known as ‘products targeting sustainable investments’, covers products targeting bespoke sustainable investments and applies “… where a financial product has sustainable investment as its objective and an index has been designated as a reference benchmark.”
Minimum investment for standard accounts.
Status.
NAV.
Turnover.
Symbol.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.mutual_fund_profile("VTSAX"))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26
{ "profile": { "benchmark": "CRSP US Total Stock Market TR", "beta": 1.05, "category": "Multi-Cap Core", "cusip": "", "deferredLoad": 0, "description": "Created in 1992, Vanguard Total Stock Market Index Fund is designed to provide investors with exposure to the entire U.S. equity market, including small-, mid-, and large-cap growth and value stocks. The fund’s key attributes are its low costs, broad diversification, and the potential for tax efficiency. Investors looking for a low-cost way to gain broad exposure to the U.S. stock market who are willing to accept the volatility that comes with stock market investing may wish to consider this fund as either a core equity holding or your only domestic stock fund.", "expenseRatio": 0.04, "fee12b1": 0, "frontLoad": 0, "fundFamily": "VANGUARD ADMIRAL", "inceptionDate": "2000-11-13", "investmentSegment": "Growth & Income", "iraMinInvestment": 0, "isin": "", "manager": "O'Reilly,Nejman", "maxRedemptionFee": 0, "name": "Vanguard Index Funds: Vanguard Total Stock Market Index Fund; Admiral Class Shares", "standardMinInvestment": 3000, "status": "Open", "totalNav": 280758000000, "turnover": 8 }, "symbol": "VTSAX" }
Get full Mutual Funds holdings/constituents. This endpoint covers both US and global mutual funds. For international funds, you must query the data using ISIN. A list of supported funds can be found here.
Method: GET
Premium: Premium required.
Examples:
/mutual-fund/holdings?symbol=VTSAX
/mutual-fund/holdings?isin=US9229087286&skip=1
/mutual-fund/holdings?isin=LU1748855837
Arguments:
Fund's symbol.
Fund's isin.
Skip the first n results. You can use this parameter to query historical constituents data. The latest result is returned if skip=0 or not set.
Response Attributes:
Holdings update date.
Array of holdings.
Asset type. Can be 1 of the following values: Equity
, ETP
, Fund
, Bond
, Other
or empty.
CUSIP.
ISIN.
Security name
Portfolio's percent
Number of shares.
Symbol description
Market value
Number of holdings.
Symbol.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.mutual_fund_holdings("VTSAX"))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27
{ "atDate": "2023-01-31", "holdings": [ { "assetType": "Equity", "cusip": "037833100", "isin": "US0378331005", "name": "Apple Inc", "percent": 5.36984, "share": 463159883, "symbol": "AAPL", "value": 66829339518 }, { "assetType": "Equity", "cusip": "594918104", "isin": "US5949181045", "name": "Microsoft Corp", "percent": 4.54903, "share": 228457719, "symbol": "MSFT", "value": 56614107345 } ], "numberOfHoldings": 3972, "symbol": "VTSAX" }
Get Mutual Funds sector exposure data.
Method: GET
Premium: Premium required.
Examples:
/mutual-fund/sector?symbol=VTSAX
/mutual-fund/sector?symbol=FNILX
Arguments:
Mutual Fund symbol.
Fund's isin.
Response Attributes:
Array of sector and exposure levels.
Percent of exposure.
Sector
Mutual symbol.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.mutual_fund_sector_exp("VTSAX"))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
{ "sectorExposure": [ { "exposure": 26.2, "sector": "Information Technology" }, { "exposure": 13.84, "sector": "Health Care" }, { "exposure": 12.29, "sector": "Consumer Discretionary" }, { "exposure": 10.46, "sector": "Financials" } ], "symbol": "VTSAX" }
Get Mutual Funds country exposure data.
Method: GET
Premium: Premium required.
Examples:
/mutual-fund/country?symbol=FNILX
/mutual-fund/country?symbol=VFIAX
Arguments:
Symbol.
Fund's isin.
Response Attributes:
Array of countries and and exposure levels.
Country
Percent of exposure.
Symbol.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.mutual_fund_country_exp("VTSAX"))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29
{ "countryExposure": [ { "country": "United States of America (the)", "exposure": 96.87 }, { "country": "Ireland", "exposure": 1.58 }, { "country": "United Kingdom of Great Britain and Northern Ireland (the)", "exposure": 0.62 }, { "country": "Switzerland", "exposure": 0.32 }, { "country": "Bermuda", "exposure": 0.29 }, { "country": "Canada", "exposure": 0.2 } ], "symbol": "VTSAX" }
Get EET data for EU funds. For PAIs data, please see the EET PAI endpoint.
Method: GET
Premium: Premium Access Required
Examples:
/mutual-fund/eet?isin=LU2036931686
Arguments:
ISIN.
Response Attributes:
EET data.
ISIN.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.mutual_fund_eet("LU2036931686"))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
{ "data":{ "boardGenderDiversityConsidered":true, "carbonFootprintScope123Considered":false, "carbonFootprintScope12Considered":false, "clientSustainabilityPreferencesConsidered":true, "controversialWeaponsConsidered":true, "energyConsumptionIntensityNACEAConsidered":false, "exposuretoEnergyEfficientRealEstateAssetsConsidered":false, "exposuretoFossilFuelSectorConsidered":false, "exposuretoFossilFuelsExtractionStorageTransportManufactureConsidered":false, "greenhouseGasEmissionsScope1Considered":false, "greenhouseGasEmissionsScope2Considered":false, "greenhouseGasEmissionsScope3Considered":false, }, "isin":"LU2036931686" }
Get EET PAI data for EU funds.
Method: GET
Premium: Premium Access Required
Examples:
/mutual-fund/eet-pai?isin=LU2036931686
Arguments:
ISIN.
Response Attributes:
EET data.
ISIN.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.mutual_fund_eet_pai("LU2036931686"))
1 2 3 4 5 6 7 8 9 10 11 12
{ "data":{ "airPollutantEmissionsCoveredHoldings":27.94263, "airPollutantEmissionsEligibleHoldings":490.89858, "airPollutantEmissionsNumberHoldingsCovered":14, "airPollutantEmissionsPctPortfolioCoverage":4.57, "airPollutantEmissionsPctPortfolioEligibleAssets":79.65, "airPollutantEmissionsTonnesPerEURm":1.28271, "antiHumanTraffickingNumberHoldingsCovered":67, }, "isin":"LU2036931686" }
Get general information of a bond. You can query by FIGI, ISIN or CUSIP. A list of supported bonds can be found here.
Method: GET
Premium: Premium Access Required
Examples:
/bond/profile?figi=BBG0152KFHS6
/bond/profile?isin=US912810TD00
Arguments:
ISIN
CUSIP
FIGI
Response Attributes:
Outstanding amount.
Asset.
Asset.
Bond type.
Callable.
Coupon.
Coupon type.
Cusip.
Dated date.
Bond type.
FIGI.
First coupon date.
Industry.
Sub-Industry.
ISIN.
Issue date.
Period.
Offering price.
Offering amount.
Payment frequency.
Security level.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.bond_profile(isin='US912810TD00'))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24
{ "isin":"US912810TD00", "cusip":"", "figi":"BBG0152KFHS6", "coupon":2.25, "maturityDate":"2052-02-15", "offeringPrice":100, "issueDate":"2022-03-15", "bondType":"US Government", "debtType":"", "industryGroup":"Government", "industrySubGroup":"U.S. Treasuries", "asset":"", "assetType":"", "datedDate":"2022-02-15", "firstCouponDate":"2022-08-15", "originalOffering":20000000000, "amountOutstanding":36914000000, "paymentFrequency":"Semi-Annual", "securityLevel":"", "callable":null, "couponType":"", "dayCount":"" }
Get bond's price data. The following datasets are supported:
Exchange | Segment | Delay |
---|---|---|
US Government Bonds | Government Bonds | End-of-day |
FINRA Trace | BTDS: US Corporate Bonds | Delayed 4h |
FINRA Trace | 144A Bonds | Delayed 4h |
Method: GET
Premium: Premium Access Required
Examples:
/bond/price?isin=US912810TD00&from=1590988249&to=1649099548
Arguments:
ISIN.
UNIX timestamp. Interval initial value.
UNIX timestamp. Interval end value.
Response Attributes:
List of close prices for returned candles.
Status of the response. This field can either be ok or no_data.
List of timestamp for returned candles.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.bond_price('US912810TD00', 1590988249, 1649099548))
1 2 3 4 5 6 7 8 9 10 11 12 13
{ "c":[ 97.5, 97.96875, 98.78125, ], "s":"ok", "t":[ 1644883200, 1644969600, 1645056000, ] }
Get trade-level data for bonds. The following datasets are supported:
Exchange | Segment | Delay |
---|---|---|
FINRA Trace | BTDS: US Corporate Bonds | Delayed 4h |
FINRA Trace | 144A Bonds | Delayed 4h |
Method: GET
Premium: Premium Access Required
Examples:
/bond/tick?isin=US693475BF18&date=2022-08-19&limit=50&skip=6&format=json&exchange=trace
Arguments:
ISIN.
Date: 2020-04-02.
Limit number of ticks returned. Maximum value: 25000
Number of ticks to skip. Use this parameter to loop through the entire data.
Currently support the following values: trace
.
Response Attributes:
ATS flag. Y or empty
List of trade conditions. A comprehensive list of trade conditions code can be found here
Number of ticks returned. If count
< limit
, all data for that date has been returned.
List of values showing the counterparty of each trade. List of supported values: here
List of price data.
List of values showing the reporting party of each trade. List of supported values: here
List of values showing the side (Buy/sell) of each trade. List of supported values: here
Number of ticks skipped.
List of timestamp in UNIX ms.
Total number of ticks for that date.
List of volume data.
List of yield data.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.bond_tick('US693475BF18', '2022-08-19', 500, 0, 'trace'))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
{ "c":[[],[],[]], "count":3, "cp":[ "3", "1", "1" ], "p":[ 100.592, 100.492, 100.234 ], "si":[ "2", "2", "2" ], "skip":6, "t":[ 1660929161000, 1660929161000, 1660929778000 ], "total":211, "v":[ 3000, 3000, 50000 ] }
Get yield curve data for Treasury bonds.
Method: GET
Premium: Premium Access Required
Examples:
Arguments:
Bond's code. You can find the list of supported code here.
Response Attributes:
Bond's code
Array of data.
Date of the reading
Value
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.bond_yield_curve('10y'))
1 2 3 4 5 6 7 8 9 10 11 12 13
{ "code": "10y", "data": [ { "d": "2022-10-31", "v": 4.1 }, { "d": "2022-11-01", "v": 4.07 } ] }
List supported forex exchanges
Method: GET
Examples:
Arguments:
Response Attributes:
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.forex_exchanges())
1 2 3 4 5 6 7
[ "oanda", "fxcm", "forex.com", "ic markets", "fxpro" ]
List supported forex symbols.
Method: GET
Examples:
Arguments:
Exchange you want to get the list of symbols from.
Response Attributes:
Symbol description
Display symbol name.
Unique symbol used to identify this symbol used in /forex/candle
endpoint.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.forex_symbols('OANDA'))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
[ { "description": "IC MARKETS Euro vs US Dollar EURUSD", "displaySymbol": "EUR/USD", "symbol": "IC MARKETS:1" }, { "description": "IC MARKETS Australian vs US Dollar AUDUSD", "displaySymbol": "AUD/USD", "symbol": "IC MARKETS:5" }, { "description": "IC MARKETS British Pound vs US Dollar GBPUSD", "displaySymbol": "GBP/USD", "symbol": "IC MARKETS:2" }]
Get candlestick data for forex symbols.
Method: GET
Premium: Premium Access Required
Examples:
/forex/candle?symbol=OANDA:EUR_USD&resolution=D&from=1572651390&to=1575243390
Arguments:
Use symbol returned in /forex/symbol
endpoint for this field.
Supported resolution includes 1, 5, 15, 30, 60, D, W, M
.Some timeframes might not be available depending on the exchange.
UNIX timestamp. Interval initial value.
UNIX timestamp. Interval end value.
Response Attributes:
List of close prices for returned candles.
List of high prices for returned candles.
List of low prices for returned candles.
List of open prices for returned candles.
Status of the response. This field can either be ok or no_data.
List of timestamp for returned candles.
List of volume data for returned candles.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.forex_candles('OANDA:EUR_USD', 'D', 1590988249, 1591852249))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39
{ "c": [ 1.10713, 1.10288, 1.10397, 1.10182 ], "h": [ 1.1074, 1.10751, 1.10729, 1.10595 ], "l": [ 1.09897, 1.1013, 1.10223, 1.10101 ], "o": [ 1.0996, 1.107, 1.10269, 1.10398 ], "s": "ok", "t": [ 1568667600, 1568754000, 1568840400, 1568926800 ], "v": [ 75789, 75883, 73485, 5138 ] }
Get rates for all forex pairs. Ideal for currency conversion
Method: GET
Premium: Premium Access Required
Examples:
/forex/rates?base=EUR&date=2022-02-10
Arguments:
Base currency. Default to EUR.
Date. Leave blank to get the latest data.
Response Attributes:
Base currency.
A map of base/quote rates for all currency pair.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.forex_rates(base='USD'))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32
{ "base": "USD", "quote": { "AED": 3.968012, "AFN": 82.373308, "ALL": 124.235408, "AMD": 520.674275, "CAD": 1.525368, "CDF": 1904.576741, "CHF": 1.053259, "CNY": 7.675235, "COP": 4282.32676, "CRC": 614.796995, "CUC": 1.080304, "CUP": 28.628067, "CVE": 110.517004, "CZK": 27.096737, "DJF": 191.991344, "DKK": 7.461229, "DOP": 59.195018, "DZD": 139.384021, "EGP": 17.018597, "ERN": 16.204913, "ETB": 36.296767, "EUR": 0.91, "GBP": 0.874841, "JPY": 114.583548, "MDL": 19.120251, "MGA": 4105.156776, "USD": 1, } }
List supported crypto exchanges
Method: GET
Examples:
Arguments:
Response Attributes:
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.crypto_exchanges())
1 2 3 4 5 6 7 8 9 10 11 12 13 14
[ "KRAKEN", "HITBTC", "COINBASE", "GEMINI", "POLONIEX", "Binance", "ZB", "BITTREX", "KUCOIN", "OKEX", "BITFINEX", "HUOBI" ]
List supported crypto symbols by exchange
Method: GET
Examples:
/crypto/symbol?exchange=binance
Arguments:
Exchange you want to get the list of symbols from.
Response Attributes:
Symbol description
Display symbol name.
Unique symbol used to identify this symbol used in /crypto/candle
endpoint.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.crypto_symbols('BINANCE'))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
[ { "description": "Binance ETHBTC", "displaySymbol": "ETH/BTC", "symbol": "ETHBTC" }, { "description": "Binance LTCBTC", "displaySymbol": "LTC/BTC", "symbol": "BINANCE:LTCBTC" }, { "description": "Binance BNBBTC", "displaySymbol": "BNB/BTC", "symbol": "BINANCE:BNBBTC" }]
Get crypto's profile.
Method: GET
Premium: Premium Access Required
Examples:
Arguments:
Crypto symbol such as BTC or ETH.
Response Attributes:
Circulating supply.
Description.
Launch date.
Logo image.
Long name.
Market capitalization.
Max supply.
Name.
Proof type.
Total supply.
Project's website.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.crypto_profile('BTC'))
1 2 3 4 5 6 7 8 9 10 11 12 13
{ "name": "Bitcoin", "longName": "Bitcoin (BTC)", "description": "Bitcoin uses peer-to-peer technology to operate with no central authority or banks; managing transactions and the issuing of bitcoins is carried out collectively by the network. Although other cryptocurrencies have come before, Bitcoin is the first decentralized cryptocurrency - Its reputation has spawned copies and evolution in the space.With the largest variety of markets and the biggest value - having reached a peak of 318 billion USD - Bitcoin is here to stay. As with any new invention, there can be improvements or flaws in the initial model however the community and a team of dedicated developers are pushing to overcome any obstacle they come across. It is also the most traded cryptocurrency and one of the main entry points for all the other cryptocurrencies. The price is as unstable as always and it can go up or down by 10%-20% in a single day.Bitcoin is an SHA-256 POW coin with almost 21,000,000 total minable coins. The block time is 10 minutes. See below for a full range of Bitcoin markets where you can trade US Dollars for Bitcoin, crypto to Bitcoin and many other fiat currencies too.Bitcoin Whitepaper PDF - A Peer-to-Peer Electronic Cash SystemBlockchain data provided by: Blockchain (main source), Blockchair (backup)", "marketCap": 1119891535870.4905, "totalSupply": 18876550, "maxSupply": 21000000, "circulatingSupply": 18876550, "logo": "", "launchDate": "2009-01-03", "website": "https://bitcoin.org/en/", "proofType": "PoW" }
Get candlestick data for crypto symbols.
Method: GET
Premium: Premium Access Required
Examples:
/crypto/candle?symbol=BINANCE:BTCUSDT&resolution=D&from=1572651390&to=1575243390
Arguments:
Use symbol returned in /crypto/symbol
endpoint for this field.
Supported resolution includes 1, 5, 15, 30, 60, D, W, M
.Some timeframes might not be available depending on the exchange.
UNIX timestamp. Interval initial value.
UNIX timestamp. Interval end value.
Response Attributes:
List of close prices for returned candles.
List of high prices for returned candles.
List of low prices for returned candles.
List of open prices for returned candles.
Status of the response. This field can either be ok or no_data.
List of timestamp for returned candles.
List of volume data for returned candles.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.crypto_candles('BINANCE:BTCUSDT', 'D', 1590988249, 1591852249))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39
{ "c": [ 1.10713, 1.10288, 1.10397, 1.10182 ], "h": [ 1.1074, 1.10751, 1.10729, 1.10595 ], "l": [ 1.09897, 1.1013, 1.10223, 1.10101 ], "o": [ 1.0996, 1.107, 1.10269, 1.10398 ], "s": "ok", "t": [ 1568667600, 1568754000, 1568840400, 1568926800 ], "v": [ 75789, 75883, 73485, 5138 ] }
Run pattern recognition algorithm on a symbol. Support double top/bottom, triple top/bottom, head and shoulders, triangle, wedge, channel, flag, and candlestick patterns.
Method: GET
Premium: Premium Access Required
Examples:
/scan/pattern?symbol=AAPL&resolution=D
Arguments:
Symbol
Supported resolution includes 1, 5, 15, 30, 60, D, W, M
.Some timeframes might not be available depending on the exchange.
Response Attributes:
Array of patterns.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.pattern_recognition('AAPL', 'D'))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55
"points": [ { "aprice": 1.09236, "atime": 1567458000, "bprice": 1.1109, "btime": 1568322000, "cprice": 1.09897, "ctime": 1568667600, "dprice": 0, "dtime": 0, "end_price": 1.1109, "end_time": 1568926800, "entry": 1.1109, "eprice": 0, "etime": 0, "mature": 0, "patternname": "Double Bottom", "patterntype": "bullish", "profit1": 1.1294, "profit2": 0, "sortTime": 1568926800, "start_price": 1.1109, "start_time": 1566853200, "status": "incomplete", "stoploss": 1.0905, "symbol": "EUR_USD", "terminal": 0 }, { "aprice": 1.09236, "atime": 1567458000, "bprice": 1.1109, "btime": 1568322000, "cprice": 1.09897, "ctime": 1568667600, "dprice": 1.13394884, "dtime": 1568926800, "entry": 1.1339, "mature": 0, "patternname": "Bat", "patterntype": "bearish", "profit1": 1.1181, "profit2": 1.1082, "przmax": 1.1339, "przmin": 1.129, "rrratio": 3.34, "sortTime": 1568667600, "status": "incomplete", "stoploss": 1.1416, "symbol": "EUR_USD", "terminal": 0, "xprice": 1.1393, "xtime": 1561669200 } ]
Get support and resistance levels for a symbol.
Method: GET
Premium: Premium Access Required
Examples:
/scan/support-resistance?symbol=IBM&resolution=D
Arguments:
Symbol
Supported resolution includes 1, 5, 15, 30, 60, D, W, M
.Some timeframes might not be available depending on the exchange.
Response Attributes:
Array of support and resistance levels.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.support_resistance('AAPL', 'D'))
1 2 3 4 5 6 7 8 9 10
{ "levels": [ 1.092360019683838, 1.1026300191879272, 1.113450050354004, 1.1233500242233276, 1.134719967842102, 1.1513700485229492 ] }
Get aggregate signal of multiple technical indicators such as MACD, RSI, Moving Average v.v. A full list of indicators can be found here.
Method: GET
Premium: Premium Access Required
Examples:
/scan/technical-indicator?symbol=AAPL&resolution=D
Arguments:
symbol
Supported resolution includes 1, 5, 15, 30, 60, D, W, M
.Some timeframes might not be available depending on the exchange.
Response Attributes:
Number of indicator signals strong buy, buy, neutral, sell, strong sell signals.
Number of indicators for each signal
Number of buy signals
Number of neutral signals
Number of sell signals
Aggregate Signal
Whether the market is trending.
ADX reading
Whether market is trending or going sideway
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.aggregate_indicator('AAPL', 'D'))
1 2 3 4 5 6 7 8 9 10 11 12 13 14
{ "technicalAnalysis": { "count": { "buy": 6, "neutral": 7, "sell": 4 }, "signal": "neutral" }, "trend": { "adx": 24.46020733373421, "trending": false } }
Return technical indicator with price data. List of supported indicators can be found here.
Method: GET
Premium: Premium Access Required
Examples:
/indicator?symbol=symbol=AAPL&resolution=D&from=1583098857&to=1584308457&indicator=sma&timeperiod=3
Arguments:
symbol
Supported resolution includes 1, 5, 15, 30, 60, D, W, M
.Some timeframes might not be available depending on the exchange.
UNIX timestamp. Interval initial value.
UNIX timestamp. Interval end value.
Indicator name. Full list can be found here.
Check out this page to see which indicators and params are supported.
Response Attributes:
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.technical_indicator(symbol="AAPL", resolution='D', _from=1583098857, to=1584308457, indicator='rsi', indicator_fields={"timeperiod": 3}))
1
{"sma":[0,0,74.23916,73.74833,73.72416,70.676666,70.045,68.911,67.41666,66.802],"t":[1583107200,1583193600,1583280000,1583366400,1583452800,1583712000,1583798400,1583884800,1583971200,1584057600]}
List earnings call transcripts' metadata. This endpoint is available for US, UK, European, Australian and Canadian companies.
Method: GET
Premium: Premium required.
Examples:
/stock/transcripts/list?symbol=AAPL
/stock/transcripts/list?symbol=AC.TO
/stock/transcripts/list?symbol=BARC.L
Arguments:
Company symbol: AAPL. Leave empty to list the latest transcripts
Response Attributes:
Company symbol.
Array of transcripts' metadata
Transcript's ID used to get the full transcript.
Quarter of earnings result in the case of earnings call transcript.
Time of the event.
Title.
Year of earnings result in the case of earnings call transcript.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.transcripts_list('AAPL'))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45
{ "symbol": "AAPL", "transcripts": [ { "id": "AAPL_326091", "quarter": 1, "symbol": "AAPL", "time": "2020-01-28 21:35:45", "title": "AAPL - Earnings Call Transcript Q1 2020", "year": 2020 }, { "id": "AAPL_322579", "quarter": 4, "symbol": "AAPL", "time": "2019-10-30 22:27:15", "title": "AAPL - Earnings Call Transcript Q4 2019", "year": 2019 }, { "id": "AAPL_318112", "quarter": 3, "symbol": "AAPL", "time": "2019-07-30 22:26:28", "title": "AAPL - Earnings Call Transcript Q3 2019", "year": 2019 }, { "id": "AAPL_313737", "quarter": 2, "symbol": "AAPL", "time": "2019-04-30 19:55:19", "title": "AAPL - Earnings Call Transcript Q2 2019", "year": 2019 }, { "id": "AAPL_308757", "quarter": 1, "symbol": "AAPL", "time": "2019-01-29 21:06:06", "title": "AAPL - Earnings Call Transcript Q1 2019", "year": 2019 } ] }
Get earnings call transcripts, audio and participants' list. Data is available for US, UK, European, Australian and Canadian companies.
15+ years of data is available with 220,000+ audio which add up to 7TB in size.
Method: GET
Premium: Premium required.
Examples:
/stock/transcripts?id=AAPL_162777
Arguments:
Transcript's id obtained with Transcripts List endpoint.
Response Attributes:
Audio link.
Transcript's ID.
Participant list
Participant's description
Participant's name
Whether the speak is a company's executive or an analyst
Quarter of earnings result in the case of earnings call transcript.
Company symbol.
Time of the event.
Title.
Transcript content.
Speaker's name
Earnings calls section (management discussion or Q&A)
Speaker's speech
Year of earnings result in the case of earnings call transcript.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.transcripts('AAPL_162777'))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33
{ "audio": "https://static.finnhub.io/transcripts_audio/4319666.mp3", "id": "AAPL_326091", "participant": [ { "name": "Tejas Gala", "description": "Senior Analyst at Corporate Finance and IR" }, { "name": "Tim Cook", "description": "CEO" } ], "quarter": 1, "symbol": "AAPL", "time": "2020-01-28 21:35:45", "title": "AAPL - Earnings call transcripts Q1 2020", "transcript": [ { "name": "Operator", "speech": [ "Good day, everyone. Welcome to the Apple Incorporated First Quarter Fiscal Year 2020 Earnings Conference Call. Today's conference is being recorded. At this time for opening remarks and introductions, I would like to turn the call over to Tejas Gala, Senior Analyst, Corporate Finance and Investor Relations. Please go ahead." ] }, { "name": "Tejas Gala", "speech": [ "Thank you. Good afternoon, and thank you for joining us. Speaking first today is Apple's CEO, Tim Cook, and he'll be followed by CFO, Luca Maestri. After that, we'll open the call to questions from analysts. Please note that some of the information you'll hear during our discussion today will consist of forward-looking statements, including without limitation, those regarding revenue, gross margin, operating expenses, other income and expenses, taxes, capital allocation and future business outlook. Actual results or trends could differ materially from our forecast. For more information, please refer to the risk factors discussed in Apple's most recently filed periodic reports on Form 10-K and Form 10-Q and the Form 8-K filed with the SEC today, along with the associated press release. Apple assumes no obligation to update any forward-looking statements or information, which speaks as of their respective dates. I'd now like to turn the call over to Tim for introductory remarks." ] } ], "year": 2020 }
Thematic investing involves creating a portfolio (or portion of a portfolio) by gathering together a collection of companies involved in certain areas that you predict will generate above-market returns over the long term. Themes can be based on a concept such as ageing populations or a sub-sector such as robotics, and drones. Thematic investing focuses on predicted long-term trends rather than specific companies or sectors, enabling investors to access structural, one-off shifts that can change an entire industry.
This endpoint will help you get portfolios of different investment themes that are changing our life and are the way of the future.
A full list of themes supported can be found here. The theme coverage and portfolios are updated bi-weekly by our analysts. Our approach excludes penny, super-small cap and illiquid stocks.
Method: GET
Premium: Premium Access Required
Examples:
/stock/investment-theme?theme=financialExchangesData
/stock/investment-theme?theme=futureFood
Arguments:
Investment theme. A full list of themes supported can be found here.
Response Attributes:
Investment theme portfolio.
Symbol
Investment theme
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.stock_investment_theme('financialExchangesData'))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
{ "data": [ { "symbol": "ICE" }, { "symbol": "NDAQ" }, { "symbol": "CBOE" }, { "symbol": "FDS" }, { "symbol": "SPGI" }, { "symbol": "TW" } ], "theme": "financialExchangesData" }
This endpoint provides an overall map of public companies' key customers and suppliers. The data offers a deeper look into a company's supply chain and how products are created. The data will help investors manage risk, limit exposure or generate alpha-generating ideas and trading insights.
Method: GET
Premium: Premium Access Required
Examples:
/stock/supply-chain?symbol=AAPL
/stock/supply-chain?symbol=WMT
Arguments:
Symbol.
Response Attributes:
Key customers and suppliers.
Country
Whether the company is a customer.
Industry
Name
1-month price correlation
1-year price correlation
6-month price correlation
Whether the company is a supplier
Symbol
3-month price correlation
2-week price correlation
2-year price correlation
symbol
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.stock_supply_chain('AAPL'))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41
{ "data": [ { "customer": true, "name": "Costco Wholesale Corporation", "oneMonthCorrelation": 0.26, "oneYearCorrelation": 0.63, "sixMonthCorrelation": 0.87, "supplier": false, "symbol": "COST", "threeMonthCorrelation": 0.89, "twoWeekCorrelation": 0.35, "twoYearCorrelation": 0.91 }, { "customer": true, "name": "Qualcomm", "oneMonthCorrelation": 0.06, "oneYearCorrelation": 0.58, "sixMonthCorrelation": 0.87, "supplier": true, "symbol": "QCOM", "threeMonthCorrelation": 0.88, "twoWeekCorrelation": 0.71, "twoYearCorrelation": 0.94 }, { "customer": false, "name": "Foxconn Industrial Internet Co., Ltd.", "oneMonthCorrelation": 0.25, "oneYearCorrelation": -0.48, "sixMonthCorrelation": -0.65, "supplier": true, "symbol": "601138.SS", "threeMonthCorrelation": -0.79, "twoWeekCorrelation": -0.55, "twoYearCorrelation": -0.6 } ], "symbol": "AAPL" }
This endpoint provides the latest ESG scores and important indicators for 7000+ global companies. The data is collected through company's public ESG disclosure and public sources.
Our ESG scoring models takes into account more than 150 different inputs to calculate the level of ESG risks and how well a company is managing them. A higher score means lower ESG risk or better ESG management. ESG scores are in the the range of 0-100. Some key indicators might contain letter-grade score from C- to A+ with C- is the lowest score and A+ is the highest score.
Method: GET
Premium: Premium Access Required
Examples:
Arguments:
Symbol.
Response Attributes:
Map key-value pair of key ESG data points.
Environment Score
Governance Score
Social Score
symbol
Total ESG Score
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.company_esg_score("AAPL"))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53
{ "data": { "womenManagementPercentage": 17.02, "adultContent": false, "alcoholic": false, "animalTesting": false, "antitrust": "C+", "asianEmployeePercentage": 27, "asianManagementPercentage": 27, "blackEmployeePercentage": 9, "blackManagementPercentage": 4, "carbonReductionPolicy": null, "catholic": false, "climateStrategy": "A+", "co2EmissionScope1": 47430, "co2EmissionScope2": 890189, "co2EmissionScope3": 22648000, "co2EmissionTotal": 937619, "coalEnergy": false, "ecofriendlyPackaging": null, "environmentalReporting": true, "firearms": false, "fuelEfficiencyConsumption": null, "furLeather": false, "gambling": false, "gmo": false, "hazardousSubstances": null, "hispanicLatinoEmployeePercentage": 14, "hispanicLatinoManagementPercentage": 8, "humanRightsPolicy": "C-", "militaryContract": false, "nuclear": false, "palmOil": false, "pesticides": false, "privacyPolicy": "B-", "recallPolicySafety": null, "recyclingPolicy": null, "stakeholderEngagement": null, "sustainableForestryPolicy": null, "tobacco": false, "totalWomenPercentage": 34, "waterEfficiencyConsumption": null, "weapons": false, "whiteEmployeePercentage": 47, "whiteManagementPercentage": 59, "workplaceHealthSafety": null }, "environmentScore": 73.21, "governanceScore": 56.06, "socialScore": 45.81, "symbol": "AAPL", "totalESGScore": 56.04 }
This endpoint provides historical ESG scores and important indicators for 7000+ global companies. The data is collected through company's public ESG disclosure and public sources.
Our ESG scoring models takes into account more than 150 different inputs to calculate the level of ESG risks and how well a company is managing them. A higher score means lower ESG risk or better ESG management. ESG scores are in the the range of 0-100. Some key indicators might contain letter-grade score from C- to A+ with C- is the lowest score and A+ is the highest score.
Method: GET
Premium: Premium Access Required
Examples:
/stock/historical-esg?symbol=AAPL
/stock/historical-esg?symbol=WMT
Arguments:
Symbol.
Response Attributes:
Historical ESG data points.
Map key-value pair of key ESG data points.
Environment Score
Governance Score
Period
Social Score
Total ESG Score
symbol
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.company_historical_esg_score("AAPL"))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52
{ "data": [ { "data": { "adultContent": false, "alcoholic": false, "animalTesting": false, "antitrust": "62.0", "asianEmployeePercentage": 27.9, "asianManagementPercentage": 29.2, "blackEmployeePercentage": 9.4, "blackManagementPercentage": 4, "carbonReductionPolicy": "True", "catholic": true, "co2EmissionScope1": 55202, "co2EmissionScope2": 1003246, "co2EmissionScope3": 23128420, "co2EmissionTotal": 1058448, "coalEnergy": false }, "environmentScore": 61.74593, "governanceScore": 92.81813, "period": "2021-09-25", "socialScore": 76.52558, "totalESGScore": 77.02988 }, { "data": { "adultContent": false, "alcoholic": false, "animalTesting": false, "antitrust": "28.0", "asianEmployeePercentage": 27, "asianManagementPercentage": 27, "blackEmployeePercentage": 9, "blackManagementPercentage": 4, "carbonReductionPolicy": "True", "catholic": true, "co2EmissionScope1": 47430, "co2EmissionScope2": 890189, "co2EmissionScope3": 22547000, "co2EmissionTotal": 937619 }, "environmentScore": 59.460255, "governanceScore": 85.85033, "period": "2020-09-26", "socialScore": 74.40586, "totalESGScore": 73.238815 } ], "symbol": "AAPL" }
This endpoint provides Earnings Quality Score for global companies.
Earnings quality refers to the extent to which current earnings predict future earnings. "High-quality" earnings are expected to persist, while "low-quality" earnings do not. A higher score means a higher earnings quality
Finnhub uses a proprietary model which takes into consideration 4 criteria:
We then compare the metrics of each company in each category against its peers in the same industry to gauge how quality its earnings is.
Method: GET
Premium: Premium Access Required
Examples:
/stock/earnings-quality-score?symbol=AAPL&freq=quarterly
/stock/earnings-quality-score?symbol=WMT&freq=quarterly
Arguments:
Symbol.
Frequency. Currently support annual
and quarterly
Response Attributes:
Array of earnings quality score.
Cash Generation and Capital Allocation
Growth Score
Letter Score
Leverage Score
Period
Profitability Score
Total Score
Frequency
Symbol
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.company_earnings_quality_score('AAPL', 'quarterly'))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33
{ "data": [ { "capitalAllocation": 67.6878, "growth": 55.8022, "letterScore": "B+", "leverage": 24.5122, "period": "2021-06-01", "profitability": 82.3843, "score": 57.5966 }, { "capitalAllocation": 75.1464, "growth": 70.2461, "letterScore": "A-", "leverage": 39.5682, "period": "2021-03-01", "profitability": 88.4613, "score": 68.3555 }, { "capitalAllocation": 43.8708, "growth": 68.1803, "letterScore": "A-", "leverage": 56.1926, "period": "2020-12-01", "profitability": 92.6311, "score": 65.2187 }, ], "freq": "quarterly", "symbol": "AAPL" }
List USPTO patents for companies. Limit to 250 records per API call.
Method: GET
Examples:
/stock/uspto-patent?symbol=NVDA&from=2021-01-01&to=2021-12-31
Arguments:
Symbol.
From date YYYY-MM-DD
.
To date YYYY-MM-DD
.
Response Attributes:
Array of patents.
Application Number.
Array of companies' name on the patent.
Description.
Filing date.
Filing status.
Patent number.
Patent's type.
Publication date.
URL of the original article.
Symbol.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.stock_uspto_patent('NVDA', _from="2020-06-01", to="2021-06-10"))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
{ "data":[ { "applicationNumber":"17163855", "companyFilingName":[ "NVIDIA CORPORATION" ], "description":"DYNAMIC DIRECTIONAL ROUNDING", "filingDate":"2021-02-01 00:00:00", "filingStatus":"Application", "patentNumber":"US20210232366A1", "publicationDate":"2021-07-29 00:00:00", "type":"Utility", "url":"https://patentimages.storage.googleapis.com/33/ed/0c/0b6b6f87e55fea/US20210232366A1.pdf" }, { "applicationNumber":"17162550", "companyFilingName":[ "NVIDIA CORPORATION" ], "description":"REAL-TIME HARDWARE-ASSISTED GPU TUNING USING MACHINE LEARNING", "filingDate":"2021-01-29 00:00:00", "filingStatus":"Application", "patentNumber":"US20210174569A1", "publicationDate":"2021-06-10 00:00:00", "type":"Utility", "url":"https://patentimages.storage.googleapis.com/23/40/45/98b27a921d657c/US20210174569A1.pdf" } ], "symbol":"NVDA" }
Get a list of H1-B and Permanent visa applications for companies from the DOL. The data is updated quarterly.
Method: GET
Examples:
/stock/visa-application?symbol=AAPL&from=2021-01-01&to=2021-12-31
Arguments:
Symbol.
From date YYYY-MM-DD
. Filter on the beginDate
column.
To date YYYY-MM-DD
. Filter on the beginDate
column.
Response Attributes:
Array of H1b and Permanent visa applications.
Job's start date.
Case number.
Case status.
Company's name.
Job's end date.
Full-time position flag.
H1B dependent flag.
Job Title.
Quarter.
Received date.
SOC Code. A list of SOC code can be found here.
Symbol.
Visa class.
Wage level.
Wage range from.
Wage range to.
Wage unit of pay.
Worksite address.
Worksite city.
Worksite county.
Worksite postal code.
Worksite state.
Year.
Symbol.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.stock_visa_application("AAPL", "2021-01-01", "2022-06-15"))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
{ "data": [ { "year": 2020, "quarter": 1, "symbol": "AAPL", "caseNumber": "I-200-19268-472068", "caseStatus": "Certified", "receivedDate": "2019-09-25", "visaClass": "H-1B", "jobTitle": "ASIC DESIGN VERIFICATION ENGINEER", "socCode": "17-2072", "fullTimePosition": "Y", "beginDate": "2019-10-14", "endDate": "2022-10-13", "employerName": "APPLE INC.", "worksiteAddress": "320 S Capital of Texas Highway", "worksiteCity": "West Lake Hills", "worksiteCounty": "Travis", "worksiteState": "TX", "worksitePostalCode": "78746", "wageRangeFrom": 120000, "wageRangeTo": null, "wageUnitOfPay": "Year", "wageLevel": "II", "h1bDependent": "N" }, ... ], "symbol": "AAPL" }
Get a list of reported lobbying activities in the Senate and the House.
Method: GET
Examples:
/stock/lobbying?symbol=AAPL&from=2021-01-01&to=2022-12-31
Arguments:
Symbol.
From date YYYY-MM-DD
.
To date YYYY-MM-DD
.
Response Attributes:
Array of lobbying activities.
Client ID.
Country.
Date.
Description.
Document's URL.
Expenses reported by the company.
House registrant ID.
Income reported by lobbying firms.
Company's name.
Period.
Posted name.
Registrant ID.
Senate ID.
Symbol.
Year.
Symbol.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.stock_lobbying("AAPL", "2021-01-01", "2022-06-15"))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43
{ "data":[ { "symbol":"AAPL", "name":"APPLE, INC.", "description":"Hardware and software maunfacturer", "country":"US", "uuid":"db75bb6f-162a-433a-a997-a679eb4c6af6", "year":2020, "period":"fourth_quarter", "type":"Q4", "documentUrl":"https://lda.senate.gov/filings/public/filing/db75bb6f-162a-433a-a997-a679eb4c6af6/print/", "income":40000, "expenses":null, "postedName":"", "dtPosted":"", "clientId":"173094", "registrantId":"86196", "senateId":"86196-173094", "houseRegistrantId":"36548" }, { "symbol":"AAPL", "name":"APPLE INC", "description":"", "country":"US", "uuid":"cad6db2f-c3ca-4b9d-bc24-4c56fc7eaadb", "year":2020, "period":"fourth_quarter", "type":"Q4", "documentUrl":"https://lda.senate.gov/filings/public/filing/cad6db2f-c3ca-4b9d-bc24-4c56fc7eaadb/print/", "income":null, "expenses":1450000, "postedName":"", "dtPosted":"", "clientId":"103979", "registrantId":"4152", "senateId":"4152-103979", "houseRegistrantId":"31450" } ], "symbol":"AAPL" }
Get a list of government's spending activities from USASpending dataset for public companies. This dataset can help you identify companies that win big government contracts which is extremely important for industries such as Defense, Aerospace, and Education.
Method: GET
Examples:
/stock/usa-spending?symbol=LMT&from=2021-01-01&to=2022-12-31
/stock/usa-spending?symbol=BA&from=2021-01-01&to=2022-12-31
Arguments:
Symbol.
From date YYYY-MM-DD
. Filter for actionDate
To date YYYY-MM-DD
. Filter for actionDate
Response Attributes:
Array of government's spending data points.
Period.
Description.
Award agency.
Award office name.
Award sub-agency.
Recipient's country.
NAICS code.
Performance city.
Performance congressional district.
Performance country.
Performance county.
Performance end date.
Performance start date.
Performance state.
Performance zip code.
Permalink.
Company's name.
Company's name.
Symbol.
Income reported by lobbying firms.
Symbol.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.stock_usa_spending("AAPL", "2021-01-01", "2022-06-15"))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27
{ "data":[ { "symbol":"AAPL", "recipientName":"APPLE INC.", "recipientParentName":"APPLE INC.", "country":"USA", "totalValue":4238, "actionDate":"2021-11-12", "performanceStartDate":"2021-11-12", "performanceEndDate":"2021-12-10", "awardingAgencyName":"SMITHSONIAN INSTITUTION (SI)", "awardingSubAgencyName":"SMITHSONIAN INSTITUTION", "awardingOfficeName":"SMITHSONIAN ASTROPHYSICAL OBSERVATORY", "performanceCountry":"USA", "performanceCity":"CUPERTINO", "performanceCounty":"SANTA CLARA", "performanceState":"CALIFORNIA", "performanceZipCode":"950140642", "performanceCongressionalDistrict":"17", "awardDescription":"MACBOOK PRO", "naicsCode":"334111", "permalink":"https://www.usaspending.gov/award/CONT_AWD_33131222P00465925_3300_-NONE-_-NONE-/" } ], "symbol":"AAPL" }
Get stock trades data disclosed by members of congress.
Method: GET
Premium: Premium Access Required
Examples:
/stock/congressional-trading?symbol=AAPL
Arguments:
Symbol of the company: AAPL.
From date YYYY-MM-DD
.
To date YYYY-MM-DD
.
Response Attributes:
Array of stock trades.
Transaction amount from.
Transaction amount to.
Asset name.
Filing date.
Name of the representative.
Owner Type.
Position.
Symbol.
Transaction date.
Transaction type Sale
or Purchase
.
Symbol of the company.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.congressional_trading('AAPL', '2020-01-01', '2023-03-31'))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29
{ "data": [ { "amountFrom": 100001, "amountTo": 250000, "assetName": "Oppenheimer SteelPath MLP Select 40 Y (NASDAQ)", "filingDate": "2015-05-14", "name": "Lamar Alexander", "ownerType": "Spouse", "position": "senator", "symbol": "MLPTX", "transactionDate": "2014-04-04", "transactionType": "Purchase" }, { "amountFrom": 1001, "amountTo": 15000, "assetName": "Oppenheimer SteelPath MLP Select 40 Y (NASDAQ)", "filingDate": "2015-05-14", "name": "Lamar Alexander", "ownerType": "Spouse", "position": "senator", "symbol": "MLPTX", "transactionDate": "2014-02-07", "transactionType": "Purchase" } ], "symbol": "MLPTX" }
Get real-time updates on the number of COVID-19 (Corona virus) cases in the US with a state-by-state breakdown. Data is sourced from CDC and reputable sources. You can also access this API here
Method: GET
Examples:
Arguments:
Response Attributes:
Number of confirmed cases.
Number of confirmed deaths.
State.
Updated time.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.covid19())
1 2 3 4 5 6 7 8 9 10 11 12 13 14
[ { "state": "New York", "case": 8403, "death": 46, "updated": "2020-03-20 21:38:50" }, { "state": "Washington", "case": 1524, "death": 83, "updated": "2020-03-20 21:38:50" } ]
FDA's advisory committees are established to provide functions which support the agency's mission of protecting and promoting the public health, while meeting the requirements set forth in the Federal Advisory Committee Act. Committees are either mandated by statute or established at the discretion of the Department of Health and Human Services. Each committee is subject to renewal at two-year intervals unless the committee charter states otherwise.
Method: GET
Examples:
/fda-advisory-committee-calendar
Arguments:
Response Attributes:
Event's description.
Start time of the event in EST.
End time of the event in EST.
URL.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.fda_calendar())
1 2 3 4 5 6 7 8 9 10 11 12 13 14
[ { "fromDate": "2016-01-11 19:00:00", "toDate": "2016-01-11 19:00:00", "eventDescription": "January 12, 2016: Meeting of the Psychopharmacologic Drugs Advisory Committee Meeting Announcement - 01/11/2016 - 01/11/2016", "url": "https://www.fda.gov/advisory-committees/advisory-committee-calendar/january-12-2016-meeting-psychopharmacologic-drugs-advisory-committee-meeting-announcement-01112016" }, { "fromDate": "2016-01-14 13:00:00", "toDate": "2016-01-14 17:00:00", "eventDescription": "January 14, 2016: Vaccines and Related Biological Products Advisory Committee Meeting Announcement - 01/14/2016 - 01/14/2016", "url": "https://www.fda.gov/advisory-committees/advisory-committee-calendar/january-14-2016-vaccines-and-related-biological-products-advisory-committee-meeting-announcement" } ]
The Flight Ticket Price Index API provides comprehensive data on airline ticket prices, including the average daily ticket price and its percentage change (price index). This data, collected weekly and projected two weeks ahead, aggregates daily prices and indexes from the 50 busiest and largest airports across the USA. The dataset includes detailed information on airlines, dates, and average ticket prices, offering valuable insights for market analysis and pricing strategies.
The price index is calculated as percentage change of average daily ticket price from the previous weekly reading. Raw ticket prices data is available for Enterprise users. Contact us to inquire about the raw price data.
Method: GET
Premium: Accessible with Fundamental data or All in One subscription.
Examples:
/airline/price-index?airline=united&from=2024-06-01&to=2024-07-15
Arguments:
Filter data by airline. Accepted values: united
,delta
,american_airlines
,southwest
,southern_airways_express
,alaska_airlines
,frontier_airlines
,jetblue_airways
,spirit_airlines
,sun_country_airlines
,breeze_airways
,hawaiian_airlines
From date YYYY-MM-DD
.
To date YYYY-MM-DD
.
Response Attributes:
Airline name
Array of price index.
Daily average ticket price.
Date
Price Index
From date
To date
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.airline_price_index('united', _from="2024-06-01", to="2024-07-10"))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49
{ "data": [ { "airline": "united", "date": "2024-06-17", "priceIndex": 0.832755, "dailyAvgPrice": 360.918 }, { "airline": "united", "date": "2024-06-19", "priceIndex": 0.850855, "dailyAvgPrice": 307.089 }, { "airline": "united", "date": "2024-06-20", "priceIndex": 1.33928, "dailyAvgPrice": 411.278 }, { "airline": "united", "date": "2024-06-21", "priceIndex": 1.0872, "dailyAvgPrice": 447.143 }, { "airline": "united", "date": "2024-06-22", "priceIndex": 0.994883, "dailyAvgPrice": 444.855 }, { "airline": "united", "date": "2024-06-23", "priceIndex": 1, "dailyAvgPrice": 784.301 }, { "airline": "united", "date": "2024-06-24", "priceIndex": 0.857554, "dailyAvgPrice": 672.58 } ], "from": "2024-04-04", "to": "2024-07-10", "airline": "united" }
List all countries and metadata.
Method: GET
Examples:
Arguments:
Response Attributes:
Alpha 2 code
Alpha 3 code
UN code
Country name
Country risk premium
Currency name
Currency code
Default spread
Equity risk premium
Moody's credit risk rating.
Region
Sub-Region
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.country())
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30
[ { "code2": "US", "code3": "USA", "codeNo": "840", "country": "United States", "countryRiskPremium": 0, "currency": "US Dollar", "currencyCode": "USD", "defaultSpread": 0, "equityRiskPremium": 5, "rating": "Aaa", "region": "Americas", "subRegion": "Northern America" }, { "code2": "GB", "code3": "GBR", "codeNo": "826", "country": "United Kingdom of Great Britain and Northern Ireland", "countryRiskPremium": 0.91, "currency": "Sterling", "currencyCode": "GBP", "defaultSpread": 0.64, "equityRiskPremium": 5.91, "rating": "Aa3", "region": "Europe", "subRegion": "Northern Europe" } ]
Get recent and upcoming economic releases.
Historical events and surprises are available for Enterprise clients.
Method: GET
Premium: Premium Access Required
Examples:
Arguments:
From date YYYY-MM-DD
.
To date YYYY-MM-DD
.
Response Attributes:
Array of economic events.
Actual release
Country
Estimate
Event
Impact level
Previous release
Release time
Unit
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.calendar_economic())
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24
{ "economicCalendar": [ { "actual": 8.4, "country": "AU", "estimate": 6.9, "event": "Australia - Current Account Balance", "impact": "low", "prev": 1, "time": "2020-06-02 01:30:00", "unit": "AUD" }, { "actual": 0.5, "country": "AU", "estimate": 0.4, "event": "Australia- Net Exports", "impact": "low", "prev": -0.1, "time": "2020-06-02 01:30:00", "unit": "%" } ] }
List codes of supported economic data.
Method: GET
Premium: Accessible with Fundamental data or All in One subscription.
Examples:
Arguments:
Response Attributes:
Finnhub economic code used to get historical data
Country
Indicator name
Unit
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.economic_code())
1 2 3 4 5 6 7 8 9 10 11 12 13 14
[ { "code": "MA-USA-656880", "country": "USA", "name": "1-Day Repo Rate", "unit": "%" }, { "code": "MA-USA-6667797870", "country": "USA", "name": "ISM Purchasing Managers Index", "unit": "unit" } ]
Get economic data.
Method: GET
Premium: Accessible with Fundamental data or All in One subscription.
Examples:
Arguments:
Economic code.
Response Attributes:
Finnhub economic code
Array of economic data for requested code.
Date of the reading
Value
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.economic_data('MA-USA-656880'))
1 2 3 4 5 6 7 8 9 10 11 12 13
{ "code": "MA-USA-656880", "data": [ { "date": "2020-05-31", "value": -2760 }, { "date": "2020-04-30", "value": -19557 } ] }
List filings for international companies. Limit to 500 documents at a time. These are the documents we use to source our fundamental data. Only support SEDAR and UK Companies House for normal usage. Enterprise clients who need access to the full filings for global markets should contact us for the access.
Method: GET
Premium: Access approved on a case by case basis
Examples:
/stock/international-filings?symbol=RY.TO
/stock/international-filings?country=CA
Arguments:
Symbol. Leave empty to list latest filings.
Filter by country using country's 2-letter code.
From date: 2023-01-15.
To date: 2023-12-16.
Response Attributes:
Category.
Company name.
Country.
Document's description.
Filed date %Y-%m-%d %H:%M:%S
.
Language.
Symbol.
Document's title.
Url.
1 2 3 4 5
import finnhub finnhub_client = finnhub.Client(api_key="") print(finnhub_client.international_filings('AC.TO'))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24
[ { "symbol": "MINDTREE.NS", "companyName": "MindTree Limited", "filedDate": "2015-03-31 20:27:00", "category": "Resignation of Director", "title": "MindTree Limited has informed the Exchange that Mr. David B Yoffie has resigned as Independent Director of the company. The Board of Directors have accepted his resignation effective March 30, 2015.", "description": "", "url": "https://finnhub.io/international-filings?id=523566", "language": "en", "country": "IN" }, { "symbol": "INOXLEISUR.NS", "companyName": "INOX Leisure Limited", "filedDate": "2015-03-31 20:24:00", "category": "Updates", "title": "INOX Leisure Limited has informed the Exchange regarding Commencement of Commercial Operations of Multiplex Cinema Theatre situated at E-wing, Osia Commercial Arcade, SGPDA Market Complex, Margao, Goa 403601.", "description": "", "url": "https://finnhub.io/international-filings?id=52152", "language": "en", "country": "IN" } ]
Search for best-matched filings across global companies' filings, transcripts and press releases. You can filter by anything from symbol, ISIN to form type, and document sources.
This endpoint will return a list of documents that match your search criteria. If you would like to get the excerpts as well, please set highlighted
to true
. Once you have the list of documents, you can get a list of excerpts and positions to highlight the document using the /search-in-filing
endpoint
Method: POST
Premium: Premium Access Required
Examples:
Payload:
List of SEC's exchanges act to search, comma separated. Look at /filter
endpoint to see all available values.
List of market capitalization to search, comma separated. Look at /filter
endpoint to see all available values.
List of Companies House number to search, comma separated (Max: 50).
List of SEC Center Index Key to search, comma separated (Max: 50).
List of sources to search, comma separated (Max: 50). Look at /filter
endpoint to see all available values.
List of cusip to search, comma separated (Max: 50).
List of exchanges to search, comma separated (Max: 50). Look at /filter
endpoint to see all available values.
List of exhibits to search, comma separated (Max: 50). Look at /filter
endpoint to see all available values.
List of forms to search, comma separated (Max: 50). Look at /filter
endpoint to see all available values.
Search from date in format: YYYY-MM-DD, default from the last 2 years
List of gics to search, comma separated (Max: 50). Look at /filter
endpoint to see all available values.
Enable highlight in returned filings. If enabled, only return 10 results each time
List of isin to search, comma separated (Max: 50).
List of sources to search, comma separated (Max: 50). Look at /filter
endpoint to see all available values.
Use for pagination, default to page 1
Search query
List of SEDAR issuer number to search, comma separated (Max: 50).
List of sedols to search, comma separated (Max: 50).
Sort result by, default: sortMostRecent. Look at /filter
endpoint to see all available values.
List of sources to search, comma separated (Max: 50). Look at /filter
endpoint to see all available values.
List of symbols to search, comma separated (Max: 50).
Search to date in format: YYYY-MM-DD, default to today
Response Attributes:
Total filing matched your search criteria.
Filing match your search criteria.
Date the filing is submitted.
Amendment
Number of document in this filing
Date the filing is made available to the public
Id of the entity submitted the filing
Filing Id in Alpharesearch platform
Filing Form
Filer name
Estimate number of page when printing
Date as which the filing is reported
Filing Source
List of symbol associate with this filing
Filing title
Current search page
Time took to execute your search query on our server, value in ms.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
import requests import json url = "https://finnhub.io/api/v1/global-filings/search?token=" payload = json.dumps({ "query": "artificial intelligence", "symbols": "AAPL,GOOGL,TSLA", "fromDate": "2010-01-01", "toDate": "2022-09-30" }) response = requests.request("POST", url, data=payload) print(response.json())
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26
{ "count": 8, "filings": [ { "acceptanceDate": "2022-10-27 00:00:00", "amend": false, "documentCount": 1, "filedDate": "2022-10-27", "filerId": "3285503214", "filingId": "AAPL_1113753", "form": "TR/E", "name": "Apple Inc", "pageCount": 4, "reportPeriod": "", "source": "TR", "symbols": [ "AAPL" ], "title": "AAPL - Earnings call Q4 2022", "url": "https://alpharesearch.io/platform/share?filingId=AAPL_1113753" } ... ], "page": 1, "took": 1986 }
Get a list of excerpts and highlight positions within a document using your query.
Method: POST
Premium: Premium Access Required
Examples:
/global-filings/search-in-filing
Payload:
Filing Id to search
Search query
Response Attributes:
Date the filing is submitted.
Amendment
Number of document in this filing
Document for this filing.
AlphaResearch internal document id.
Highlighted excerpts for this document
Highlighted content
End offset of highlighted content
Location of the content in the rendered document
Start offset of highlighted content
Format of this document (can be html or pdf)
Number of hit in this document
Title for this document.
Link to render this document
Date the filing is make available to the public
Id of the entity submitted the filing
Filing Id in Alpharesearch platform
Filing Form
Filer name
Estimate number of page when printing
Date as which the filing is reported
Filing Source
List of symbol associate with this filing
Filing title
1 2 3 4 5 6 7 8 9 10 11 12 13 14
import requests import json url = "https://finnhub.io/api/v1/global-filings/search-in-filing?token=" payload = json.dumps({ "query": "covid", "filingId": "AAPL_1113753" }) response = requests.request("POST", url, data=payload) print(response.json())
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36
{ "acceptanceDate": "2022-10-27 00:00:00", "amend": false, "documentCount": 1, "documents": [ { "documentId": "AAPL_1113753", "excerpts": [ { "content": "If you compare it to pre-<span class='search-highlight'>pandemic</span> kind of levels, that has not returned to pre <span class='search-highlight'>pandemic</span> levels by any means.\n", "endOffset": 494, "snippetId": "tran-46", "startOffset": 385 } ... ], "format": "html", "hits": 5, "title": "Transcript", "url": "https://alpharesearch.io/filing/transcript?documentId=AAPL_1113753" } ], "filedDate": "2022-10-27", "filerId": "4295905573", "filingId": "AAPL_1113753", "form": "TR/E", "name": "Apple Inc", "pageCount": 4, "reportPeriod": "", "source": "TR", "symbols": [ "AAPL" ], "title": "AAPL - Earnings call Q4 2022", "url": "https://alpharesearch.io/platform/share?filingId=AAPL_1113753" }
Get available values for each filter in search body.
Method: GET
Premium: Premium Access Required
Examples:
/global-filings/filter?field=forms&source=SEC
Arguments:
Field to get available filters. Available filters are "countries", "exchanges", "exhibits", "forms", "gics", "naics", "caps", "acts", and "sort".
Get available forms for each source.
Response Attributes:
Filter id, use with respective field in search query body.
Display name.
1 2 3 4 5 6 7 8
import requests url = "https://finnhub.io/api/v1/global-filings/filter?field=sources&token=" response = requests.request("GET", url) print(response.json())
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30
[ { "id": "SEC", "name": "US SEC Edgar Filings" }, { "id": "TR", "name": "Event Transcripts" }, { "id": "SEDAR", "name": "Canada SEDAR Filings" }, { "id": "CH", "name": "UK Companies House Filings" }, { "id": "PR", "name": "Press Releases" }, { "id": "RR", "name": "Research Reports" }, { "id": "GF", "name": "Global Filings" } ]
Download filings using document ids.
Method: GET
Premium: Premium Access Required
Examples:
/global-filings/download?documentId=AAPL_1113753
/global-filings/download?documentId=6f2e66a1eb9a1ef4c792e479eea7964058306768a2fdef770ae4cb10baba5821
Arguments:
Document's id. Note that this is different from filingId as 1 filing can contain multiple documents.
1 2 3 4 5 6 7 8
import requests url = "https://finnhub.io/api/v1/global-filings/download?documentId=AAPL_1113753&token=" response = requests.request("GET", url) print(response.json())
Social Sentiment Premium
Get social sentiment for stocks on Reddit and Twitter.
Method:
GET
Premium: Premium required.
Examples:
/stock/social-sentiment?symbol=GME
Arguments:
Company symbol.
From date
YYYY-MM-DD
.To date
YYYY-MM-DD
.Response Attributes:
Sentiment data.
Period.
Number of mentions
Number of negative mentions
Negative score. Range 0-1
Number of positive mentions
Positive score. Range 0-1
Final score. Range: -1 to 1 with 1 is very positive and -1 is very negative
Company symbol.