fmp-api

Financial Modeling Prep (FMP) API Integration

Comprehensive financial data API specializing in fundamental analysis, SEC filings, institutional holdings (13F), congressional trading data, and pre-computed valuations.

Quick Start

Authentication

# Environment variable (recommended)
export FMP_API_KEY="your_api_key"

# Or in .env file
FMP_API_KEY=your_api_key

Basic Usage (Python)

import requests
import os

API_KEY = os.getenv("FMP_API_KEY")
BASE_URL = "https://financialmodelingprep.com/stable"

def get_quote(symbol: str) -> dict:
    """Get real-time quote for a symbol."""
    response = requests.get(
        f"{BASE_URL}/quote",
        params={"symbol": symbol, "apikey": API_KEY}
    )
    data = response.json()
    return data[0] if data else {}

# Example
quote = get_quote("AAPL")
print(f"AAPL: ${quote['price']:.2f} ({quote['changePercentage']:+.2f}%)")

Important: New Endpoint Format

FMP migrated to /stable/ endpoints. Legacy /api/v3/ endpoints require existing subscriptions.

# NEW format (use this)
BASE_URL = "https://financialmodelingprep.com/stable"

# OLD format (legacy only)
# BASE_URL = "https://financialmodelingprep.com/api/v3"

API Endpoints Reference

Stock Quotes & Prices

Endpoint	Description	Free
/quote	Real-time quote	✅
/quote-short	Quick price	✅
/historical-price-eod/full	Historical EOD	✅
/historical-price-intraday	Intraday prices	⚠️ Paid
/pre-post-market-quote	Extended hours	⚠️ Paid

Financial Statements

Endpoint	Description	Free
/income-statement	Income statement	✅
/balance-sheet-statement	Balance sheet	✅
/cash-flow-statement	Cash flow	✅
/income-statement-growth	Income growth	✅
/key-metrics	Key metrics	✅
/financial-ratios	Financial ratios	✅
/enterprise-values	Enterprise value	✅

Valuations & Analysis

Endpoint	Description	Free
/discounted-cash-flow	DCF valuation	✅
/historical-discounted-cash-flow	Historical DCF	✅
/rating	Company rating	✅
/historical-rating	Rating history	✅
/company-outlook	Full company data	✅

Institutional & Insider Data

Endpoint	Description	Free
/institutional-holder	Institutional owners	⚠️ Paid
/mutual-fund-holder	Mutual fund owners	⚠️ Paid
/insider-trading	Insider transactions	⚠️ Paid
/form-13f	13F filings	⚠️ Paid
/senate-trading	Senate trades	⚠️ Paid
/house-trading	House trades	⚠️ Paid

Screening & Discovery

Endpoint	Description	Free
/stock-screener	Screen stocks	⚠️ Paid
/stock-grade	Stock grades	✅
/search	Search symbols	✅
/search-name	Search by name	✅
/profile	Company profile	✅

Calendars & Events

Endpoint	Description	Free
/earnings-calendar	Earnings dates	✅
/ipo-calendar	IPO dates	✅
/stock-dividend-calendar	Dividends	✅
/stock-split-calendar	Stock splits	✅
/economic-calendar	Economic events	✅

SEC Filings

Endpoint	Description	Free
/sec-filings	All SEC filings	✅
/rss-feed-sec-filings	SEC RSS feed	✅

Rate Limits

Tier	Calls/Day	Calls/Min	Price
Free	250	N/A	$0
Starter	Unlimited	300	$22/mo
Premium	Unlimited	750	$59/mo
Ultimate	Unlimited	3,000	$149/mo

Free tier limitations:

• ~100 sample symbols (AAPL, TSLA, AMZN, etc.)
• End-of-day data only
• 500MB bandwidth (30-day rolling)

Common Tasks

Task: Get Financial Statements

def get_financials(symbol: str, period: str = "annual") -> dict:
    """Get comprehensive financial statements."""

    income = requests.get(
        f"{BASE_URL}/income-statement",
        params={"symbol": symbol, "period": period, "apikey": API_KEY}
    ).json()

    balance = requests.get(
        f"{BASE_URL}/balance-sheet-statement",
        params={"symbol": symbol, "period": period, "apikey": API_KEY}
    ).json()

    cashflow = requests.get(
        f"{BASE_URL}/cash-flow-statement",
        params={"symbol": symbol, "period": period, "apikey": API_KEY}
    ).json()

    return {
        "income_statement": income[0] if income else {},
        "balance_sheet": balance[0] if balance else {},
        "cash_flow": cashflow[0] if cashflow else {}
    }

# Example
financials = get_financials("AAPL")
print(f"Revenue: ${financials['income_statement'].get('revenue', 0):,.0f}")

Task: Get Key Metrics & Ratios

def get_key_metrics(symbol: str) -> dict:
    """Get important financial metrics."""

    metrics = requests.get(
        f"{BASE_URL}/key-metrics",
        params={"symbol": symbol, "period": "annual", "apikey": API_KEY}
    ).json()

    ratios = requests.get(
        f"{BASE_URL}/financial-ratios",
        params={"symbol": symbol, "period": "annual", "apikey": API_KEY}
    ).json()

    latest_metrics = metrics[0] if metrics else {}
    latest_ratios = ratios[0] if ratios else {}

    return {
        "market_cap": latest_metrics.get("marketCap"),
        "pe_ratio": latest_ratios.get("priceEarningsRatio"),
        "pb_ratio": latest_ratios.get("priceToBookRatio"),
        "roe": latest_ratios.get("returnOnEquity"),
        "roa": latest_ratios.get("returnOnAssets"),
        "debt_equity": latest_ratios.get("debtEquityRatio"),
        "current_ratio": latest_ratios.get("currentRatio"),
        "gross_margin": latest_ratios.get("grossProfitMargin"),
        "operating_margin": latest_ratios.get("operatingProfitMargin"),
        "net_margin": latest_ratios.get("netProfitMargin"),
        "dividend_yield": latest_ratios.get("dividendYield"),
        "payout_ratio": latest_ratios.get("payoutRatio")
    }

Task: Get DCF Valuation

def get_dcf_valuation(symbol: str) -> dict:
    """Get pre-computed DCF valuation."""
    response = requests.get(
        f"{BASE_URL}/discounted-cash-flow",
        params={"symbol": symbol, "apikey": API_KEY}
    )
    data = response.json()

    if data:
        dcf = data[0]
        return {
            "symbol": dcf.get("symbol"),
            "dcf_value": dcf.get("dcf"),
            "stock_price": dcf.get("stockPrice"),
            "upside": ((dcf.get("dcf", 0) / dcf.get("stockPrice", 1)) - 1) * 100
        }
    return {}

# Example
dcf = get_dcf_valuation("AAPL")
print(f"DCF Value: ${dcf['dcf_value']:.2f} ({dcf['upside']:+.1f}% upside)")

Task: Get Company Profile

def get_company_profile(symbol: str) -> dict:
    """Get comprehensive company information."""
    response = requests.get(
        f"{BASE_URL}/profile",
        params={"symbol": symbol, "apikey": API_KEY}
    )
    data = response.json()

    if data:
        profile = data[0]
        return {
            "name": profile.get("companyName"),
            "symbol": profile.get("symbol"),
            "sector": profile.get("sector"),
            "industry": profile.get("industry"),
            "market_cap": profile.get("mktCap"),
            "price": profile.get("price"),
            "beta": profile.get("beta"),
            "ceo": profile.get("ceo"),
            "website": profile.get("website"),
            "description": profile.get("description"),
            "employees": profile.get("fullTimeEmployees"),
            "exchange": profile.get("exchange"),
            "ipo_date": profile.get("ipoDate")
        }
    return {}

Task: Get Earnings Calendar

def get_earnings_calendar(from_date: str, to_date: str) -> list:
    """Get upcoming earnings announcements."""
    response = requests.get(
        f"{BASE_URL}/earnings-calendar",
        params={
            "from": from_date,
            "to": to_date,
            "apikey": API_KEY
        }
    )
    return response.json()

# Example
from datetime import datetime, timedelta
today = datetime.now()
next_week = today + timedelta(days=7)

earnings = get_earnings_calendar(
    today.strftime("%Y-%m-%d"),
    next_week.strftime("%Y-%m-%d")
)

for e in earnings[:5]:
    print(f"{e['symbol']}: {e['date']} ({e.get('time', 'N/A')})")

Task: Get Historical Prices

def get_historical_prices(symbol: str, start: str = None, end: str = None) -> list:
    """Get historical end-of-day prices."""
    params = {"symbol": symbol, "apikey": API_KEY}
    if start:
        params["from"] = start
    if end:
        params["to"] = end

    response = requests.get(
        f"{BASE_URL}/historical-price-eod/full",
        params=params
    )
    data = response.json()
    return data.get("historical", [])

# Example
prices = get_historical_prices("AAPL", "2025-01-01", "2025-12-01")
print(f"Got {len(prices)} days of data")

Task: Search for Companies

def search_companies(query: str, limit: int = 10) -> list:
    """Search for companies by name or symbol."""
    response = requests.get(
        f"{BASE_URL}/search",
        params={
            "query": query,
            "limit": limit,
            "apikey": API_KEY
        }
    )
    return response.json()

# Example
results = search_companies("Apple")
for r in results[:5]:
    print(f"{r['symbol']}: {r['name']} ({r['exchangeShortName']})")

Task: Get SEC Filings

def get_sec_filings(symbol: str, filing_type: str = None) -> list:
    """Get SEC filings for a company."""
    params = {"symbol": symbol, "apikey": API_KEY}
    if filing_type:
        params["type"] = filing_type  # 10-K, 10-Q, 8-K, etc.

    response = requests.get(
        f"{BASE_URL}/sec-filings",
        params=params
    )
    return response.json()

# Example: Get 10-K filings
filings = get_sec_filings("AAPL", "10-K")
for f in filings[:3]:
    print(f"{f['type']}: {f['fillingDate']} - {f['link']}")

Error Handling

def safe_api_call(endpoint: str, params: dict) -> dict:
    """Make API call with error handling."""
    params["apikey"] = API_KEY

    try:
        response = requests.get(f"{BASE_URL}/{endpoint}", params=params)
        data = response.json()

        # Check for error messages
        if isinstance(data, dict) and "Error Message" in data:
            print(f"API Error: {data['Error Message']}")
            return {}

        # Check for empty response
        if not data:
            print(f"No data returned for {endpoint}")
            return {}

        return data

    except requests.exceptions.RequestException as e:
        print(f"Request error: {e}")
        return {}
    except ValueError as e:
        print(f"JSON decode error: {e}")
        return {}

Free vs Paid Features

Free Tier Includes

• 250 API calls/day
• ~100 sample symbols
• Financial statements
• Key metrics & ratios
• DCF valuations
• Company profiles
• Earnings calendar
• SEC filings list
• Basic historical data

Paid Features (Starter+)

• Unlimited symbols
• Intraday data
• Stock screener
• International stocks
• Institutional holders
• Mutual fund holders
• ETF holdings breakdown

Paid Features (Premium+)

• Higher rate limits
• 13F filings
• Insider trading
• Congressional trading (Senate/House)
• Analyst estimates
• Earnings transcripts
• Extended hours data

Unique FMP Features

1. Pre-computed DCF - Ready-to-use valuations
2. Congressional Trading - Senate/House STOCK Act data
3. 13F Filings - Institutional holdings analysis
4. Standardized Financials - Normalized line items
5. Company Outlook - All data in one endpoint
6. Rating System - Proprietary company ratings

Best Practices

1. Use stable endpoints - /stable/ not /api/v3/
2. Cache static data - Profiles, historical data
3. Monitor daily limits - 250 calls goes fast
4. Batch symbol lookups - Where supported
5. Store financials - They only update quarterly
6. Use company-outlook - Single call for all data

Installation

# Recommended Python wrapper
pip install --upgrade FinancialModelingPrep-Python

# Basic usage
from fmp_python.fmp import FMP
fmp = FMP(api_key="your_api_key")
profile = fmp.get_company_profile("AAPL")

Related Skills

• finnhub-api - Real-time quotes and news
• twelvedata-api - Technical indicators
• alphavantage-api - Economic indicators

References

• Official Documentation
• Pricing Plans
• Python Wrapper
• Stable API Migration