def handle_response(response):
if response.status_code == 200:
return response.json()
else:
return {"error": f"Failed to fetch data. Status code: {response.status_code}"}
def get_income_statement(ticker, period='annual', limit=5):
"""
Fetches the income statement for a given company (ticker) over a specified period and with a limit on the number of records returned.
Parameters:
-----------
ticker : str
The stock symbol or CIK (Central Index Key) for the company (e.g., 'AAPL' for Apple or '0000320193' for its CIK).
period : str, optional
The reporting period for the income statement. Allowable values are:
- 'annual' : Retrieves the annual income statement (default).
- 'quarter' : Retrieves the quarterly income statement.
limit : int, optional
Limits the number of records returned. The default value is 5.
Returns:
--------
dict or list of dict
The income statement data, including fields like date, symbol, reported currency, filing date, etc.
Example:
--------
get_income_statement('AAPL', period='annual', limit=5)
Response format:
----------------
[
{
"date": "2022-09-24",
"symbol": "AAPL",
"reportedCurrency": "USD",
"cik": "0000320193",
"fillingDate": "2022-10-28",
"acceptedDate": "2022-10-27 18:01:14",
...
},
...
]
"""
BASE_URL = "https://financialmodelingprep.com/api/v3"
params = {
"period": period, # Accepts 'annual' or 'quarter'
"limit": limit, # Limits the number of records returned
"apikey": os.environ['FMP_API_KEY'] # API Key for authentication
}
# Construct the full URL with query parameters
endpoint = f"{BASE_URL}/income-statement/{ticker}?{urlencode(params)}"
response = requests.get(endpoint)
return handle_response(response)
def ticker_search(query, limit=10, exchange='NYSE'):
"""
Searches for ticker symbols and exchanges for both equity securities and exchange-traded funds (ETFs)
by searching with the company name or ticker symbol.
Parameters:
-----------
query : str
The name or ticker symbol to search for (e.g., 'AA' for Alcoa).
limit : int, optional
Limits the number of records returned. The default is 10.
exchange : str, optional
Specifies the exchange to filter results by. Allowable values include:
- 'NYSE' : New York Stock Exchange (default).
- 'NASDAQ' : NASDAQ Exchange.
- Other exchange codes supported by the API.
Returns:
--------
dict or list of dict
The search results, including the symbol, name, currency, stock exchange, and exchange short name.
Example:
--------
ticker_search('AA', limit=10, exchange='NASDAQ')
Response format:
----------------
[
{
"symbol": "PRAA",
"name": "PRA Group, Inc.",
"currency": "USD",
"stockExchange": "NasdaqGS",
"exchangeShortName": "NASDAQ"
},
{
"symbol": "PAAS",
"name": "Pan American Silver Corp.",
"currency": "USD",
"stockExchange": "NasdaqGS",
"exchangeShortName": "NASDAQ"
},
...
]
"""
BASE_URL = "https://financialmodelingprep.com/api/v3"
params = {
"limit": limit,
"exchange": exchange,
"apikey": os.environ['FMP_API_KEY']
}
endpoint = f"{BASE_URL}/search?query={query}&{urlencode(params)}"
response = requests.get(endpoint)
return handle_response(response)
def company_profile(symbol):
"""
Fetches a company's profile, including key stats such as price, market capitalization, beta, and other essential details.
Parameters:
-----------
symbol : str
The stock ticker symbol or CIK (Central Index Key) for the company (e.g., 'AAPL' for Apple).
Returns:
--------
dict or list of dict
The company's profile data, including fields such as symbol, price, beta, market cap, industry, CEO, and description.
Example:
--------
company_profile('AAPL')
Response format:
----------------
[
{
"symbol": "AAPL",
"price": 145.30,
"beta": 1.25,
"volAvg": 98364732,
"mktCap": 2423446000000,
"lastDiv": 0.88,
"range": "122.25-157.33",
"changes": -2.00,
"companyName": "Apple Inc.",
"currency": "USD",
"cik": "0000320193",
"isin": "US0378331005",
"cusip": "037833100",
"exchange": "NasdaqGS",
"exchangeShortName": "NASDAQ",
"industry": "Consumer Electronics",
"website": "https://www.apple.com",
"description": "Apple Inc. designs, manufactures, and markets smartphones, personal computers, tablets, wearables, and accessories worldwide."
}
]
"""
BASE_URL = "https://financialmodelingprep.com/api/v3"
params = {
'apikey': os.environ['FMP_API_KEY']
}
endpoint = f"{BASE_URL}/profile/{symbol}?{urlencode(params)}"
response = requests.get(endpoint)
return handle_response(response)
def stock_grade(symbol, limit = 500):
BASE_URL = "https://financialmodelingprep.com/api/v3"
params = {
'apikey':os.environ['FMP_API_KEY'],
'limit':limit
}
endpoint = f"{BASE_URL}/grade/{symbol}?{urlencode(params)}"
response = requests.get(endpoint)
return handle_response(response)
def current_market_cap(symbol):
"""
Fetches the current market capitalization of a given company based on its stock symbol.
Parameters:
-----------
symbol : str
The stock ticker symbol for the company (e.g., 'AAPL' for Apple).
Returns:
--------
dict or list of dict
The market capitalization data, including fields such as symbol, date, and market cap.
Example:
--------
current_market_cap('AAPL')
Response format:
----------------
[
{
"symbol": "AAPL",
"date": "2023-03-02",
"marketCap": 2309048053309
}
]
"""
BASE_URL = "https://financialmodelingprep.com/api/v3"
params = {
'apikey': os.environ['FMP_API_KEY']
}
endpoint = f"{BASE_URL}/market-capitalization/{symbol}?{urlencode(params)}"
response = requests.get(endpoint)
return handle_response(response)
def historical_market_cap(symbol, from_date=None, to_date=None, limit=None):
"""
Fetches the historical market capitalization of a given company within a specified date range.
Parameters:
-----------
symbol : str
The stock ticker symbol for the company (e.g., 'AAPL' for Apple).
from_date : str, optional
The start date for the historical data in 'YYYY-MM-DD' format (e.g., '2023-10-10').
Default is None, which fetches data from the earliest available date.
to_date : str, optional
The end date for the historical data in 'YYYY-MM-DD' format (e.g., '2023-12-10').
Default is None, which fetches data up to the latest available date.
limit : int, optional
Limits the number of records returned. Default is None, which fetches all available records.
Returns:
--------
dict or list of dict
The historical market cap data, including fields such as symbol, date, and market capitalization.
Example:
--------
historical_market_cap('AAPL', from_date='2023-10-10', to_date='2023-12-10', limit=100)
Response format:
----------------
[
{
"symbol": "AAPL",
"date": "2023-03-02",
"marketCap": 2313794623242
}
]
"""
BASE_URL = "https://financialmodelingprep.com/api/v3"
params = {
'apikey': os.environ['FMP_API_KEY'],
'from': from_date,
'to': to_date,
'limit': limit
}
endpoint = f"{BASE_URL}/historical-market-capitalization/{symbol}?{urlencode(params)}"
response = requests.get(endpoint)
return handle_response(response)
def analyst_recommendations(symbol):
"""
Fetches the analyst recommendations for a given company based on its stock symbol.
This includes buy, hold, and sell ratings.
Parameters:
-----------
symbol : str
The stock ticker symbol for the company (e.g., 'AAPL' for Apple).
Returns:
--------
dict or list of dict
The analyst recommendation data, including fields such as buy, hold, sell, and strong buy ratings.
Example:
--------
analyst_recommendations('AAPL')
Response format:
----------------
[
{
"symbol": "AAPL",
"date": "2023-08-01",
"analystRatingsBuy": 21,
"analystRatingsHold": 6,
"analystRatingsSell": 0,
"analystRatingsStrongSell": 0,
"analystRatingsStrongBuy": 11
}
]
"""
BASE_URL = "https://financialmodelingprep.com/api/v3"
params = {
'apikey': os.environ['FMP_API_KEY']
}
endpoint = f"{BASE_URL}/analyst-stock-recommendations/{symbol}?{urlencode(params)}"
response = requests.get(endpoint)
return handle_response(response)
def stock_peers(symbol):
"""
Fetches a list of companies that are considered peers of the given company.
These peers are companies that trade on the same exchange, are in the same sector,
and have a similar market capitalization.
Parameters:
-----------
symbol : str
The stock ticker symbol for the company (e.g., 'AAPL' for Apple).
Returns:
--------
dict or list of dict
The peers data, including a list of peer company ticker symbols.
Example:
--------
stock_peers('AAPL')
Response format:
----------------
[
{
"symbol": "AAPL",
"peersList": [
"LPL",
"SNEJF",
"PCRFY",
"SONO",
"VZIO",
...
]
}
]
"""
params = {
'apikey': os.environ['FMP_API_KEY'],
'symbol': symbol
}
BASE_URL = "https://financialmodelingprep.com/api/v4"
endpoint = f"{BASE_URL}/stock_peers?{urlencode(params)}"
response = requests.get(endpoint)
return handle_response(response)
def earnings_historical_and_upcoming(symbol, limit=100):
"""
Fetches historical and upcoming earnings announcements for a given company.
The response includes the date, EPS (earnings per share), estimated EPS, revenue, and estimated revenue.
Parameters:
-----------
symbol : str
The stock ticker symbol for the company (e.g., 'AAPL' for Apple).
limit : int, optional
Limits the number of records returned. The default is 100.
Returns:
--------
dict or list of dict
The earnings data, including fields such as date, EPS, estimated EPS, revenue, and estimated revenue.
Example:
--------
earnings_historical_and_upcoming('AAPL', limit=100)
Response format:
----------------
[
{
"date": "1998-10-14",
"symbol": "AAPL",
"eps": 0.0055,
"epsEstimated": 0.00393,
"time": "amc",
"revenue": 1556000000,
"revenueEstimated": 2450700000,
"updatedFromDate": "2023-12-04",
"fiscalDateEnding": "1998-09-25"
}
]
"""
params = {
'apikey': os.environ['FMP_API_KEY'],
'limit': limit
}
endpoint = f"{BASE_URL}/historical/earning_calendar/{symbol}?{urlencode(params)}"
response = requests.get(endpoint)
return handle_response(response)
def intraday_stock_prices(timeframe, symbol, from_date=None, to_date=None, extended='false'):
"""
Fetches the historical intraday stock price for a given company over a specified timeframe.
Parameters:
-----------
timeframe : str
The time interval for the stock data. Allowable values are:
- '1min' : 1 minute interval
- '5min' : 5 minute interval
- '15min' : 15 minute interval
- '30min' : 30 minute interval
- '1hour' : 1 hour interval
- '4hour' : 4 hour interval
symbol : str
The stock symbol for which to retrieve the data (e.g., 'AAPL' for Apple).
from_date : str, optional
The start date for the historical data in 'YYYY-MM-DD' format (e.g., '2023-08-10').
Default is None, which fetches all available data up to the present.
to_date : str, optional
The end date for the historical data in 'YYYY-MM-DD' format (e.g., '2023-09-10').
Default is None, which fetches data from the beginning up to the current date.
extended : str, optional
Whether to fetch extended market data (pre-market and after-hours).
Allowable values:
- 'true' : Fetch extended market data
- 'false' : Fetch only regular market hours data (default).
Returns:
--------
dict or list of dict
The historical intraday stock data, including open, high, low, close, and volume for each time interval.
Example:
--------
intraday_stock_price('5min', 'AAPL', from_date='2023-08-10', to_date='2023-09-10', extended='false')
Response format:
----------------
[
{
"date": "2023-03-02 16:00:00",
"open": 145.92,
"low": 145.72,
"high": 146.00,
"close": 145.79,
"volume": 1492644
},
...
]
"""
BASE_URL = "https://financialmodelingprep.com/api/v3"
params = {
'apikey': os.environ['FMP_API_KEY'],
'from': from_date,
'to': to_date,
'extended': extended
}
endpoint = f"{BASE_URL}/historical-chart/{timeframe}/{symbol}?{urlencode(params)}"
response = requests.get(endpoint)
return handle_response(response)
def daily_stock_prices(symbol, from_date=None, to_date=None, serietype='line'):
"""
Fetches the daily End-Of-Day (EOD) stock price for a given company over a specified date range.
Parameters:
-----------
symbol : str
The stock symbol for which to retrieve the data (e.g., 'AAPL' for Apple).
from_date : str, optional
The start date for the historical data in 'YYYY-MM-DD' format (e.g., '1990-10-10').
Default is None, which fetches the earliest available data.
to_date : str, optional
The end date for the historical data in 'YYYY-MM-DD' format (e.g., '2023-10-10').
Default is None, which fetches data up to the most recent date.
serietype : str, optional
The type of data series to return. Allowable values are:
- 'line' : Line chart data (default).
- 'other types' can be specified if supported by the API in the future.
Returns:
--------
dict or list of dict
The daily stock data, including open, high, low, close, volume, adjusted close, etc.
Example:
--------
daily_stock_price('AAPL', from_date='1990-10-10', to_date='2023-10-10', serietype='line')
Response format:
----------------
{
"symbol": "AAPL",
"historical": [
{
"date": "2023-10-06",
"open": 173.8,
"high": 176.61,
"low": 173.18,
"close": 176.53,
"adjClose": 176.53,
"volume": 21712747,
"unadjustedVolume": 21712747,
"change": 2.73,
"changePercent": 1.57077,
"vwap": 175.44,
"label": "October 06, 23",
"changeOverTime": 0.0157077
},
...
]
}
"""
BASE_URL = "https://financialmodelingprep.com/api/v3"
params = {
'apikey': os.environ['FMP_API_KEY'],
'from': from_date,
'to': to_date,
'serietype': serietype
}
endpoint = f"{BASE_URL}/historical-price-full/{symbol}?{urlencode(params)}"
response = requests.get(endpoint)
return handle_response(response)