Create utils/functions.py

utils/functions.py

@@ -0,0 +1,545 @@
+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)