> ## Documentation Index
> Fetch the complete documentation index at: https://finance.chiefpriest.design/llms.txt
> Use this file to discover all available pages before exploring further.

# Stock Overview

> Get comprehensive company information and overview data

## Endpoint

<CodeGroup>
  ```bash GET Request theme={null}
  GET /api/v1/stock/{symbol}/overview
  ```

  ```bash cURL Example theme={null}
  curl "https://stocks-dev.up.railway.app/api/v1/stock/{symbol}/overview"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get("https://stocks-dev.up.railway.app/api/v1/stock/AAPL/overview")
  data = response.json()
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://stocks-dev.up.railway.app/api/v1/stock/AAPL/overview');
  const data = await response.json();
  ```
</CodeGroup>

## Parameters

<ParamField path="symbol" type="string" required>
  Stock symbol (e.g., AAPL, MSFT, GOOGL)
</ParamField>

## Response

<ResponseField name="symbol" type="string">
  Stock symbol
</ResponseField>

<ResponseField name="companyName" type="string">
  Full company name
</ResponseField>

<ResponseField name="industry" type="string">
  Company industry classification
</ResponseField>

<ResponseField name="sector" type="string">
  Market sector
</ResponseField>

<ResponseField name="marketCap" type="number">
  Market capitalization
</ResponseField>

<ResponseField name="employees" type="number">
  Number of employees
</ResponseField>

<ResponseField name="description" type="string">
  Company business description
</ResponseField>

<ResponseField name="website" type="string">
  Company website URL
</ResponseField>

<ResponseField name="headquarters" type="string">
  Company headquarters location
</ResponseField>

<ResponseField name="founded" type="string">
  Company founding year
</ResponseField>

<ResponseField name="ceo" type="string">
  Chief Executive Officer name
</ResponseField>

<ResponseField name="exchange" type="string">
  Stock exchange listing
</ResponseField>

<ResponseField name="financialMetrics" type="object">
  Key financial ratios and metrics

  <Expandable title="Financial Metrics">
    <ResponseField name="peRatio" type="number">
      Price-to-Earnings ratio
    </ResponseField>

    <ResponseField name="pegRatio" type="number">
      Price/Earnings to Growth ratio
    </ResponseField>

    <ResponseField name="priceToBook" type="number">
      Price-to-Book ratio
    </ResponseField>

    <ResponseField name="priceToSales" type="number">
      Price-to-Sales ratio
    </ResponseField>

    <ResponseField name="dividendYield" type="number">
      Annual dividend yield percentage
    </ResponseField>

    <ResponseField name="beta" type="number">
      Stock volatility relative to market
    </ResponseField>

    <ResponseField name="eps" type="number">
      Earnings per share (trailing 12 months)
    </ResponseField>

    <ResponseField name="revenue" type="number">
      Annual revenue
    </ResponseField>

    <ResponseField name="grossMargin" type="number">
      Gross profit margin percentage
    </ResponseField>

    <ResponseField name="operatingMargin" type="number">
      Operating profit margin percentage
    </ResponseField>

    <ResponseField name="netMargin" type="number">
      Net profit margin percentage
    </ResponseField>

    <ResponseField name="roe" type="number">
      Return on Equity percentage
    </ResponseField>

    <ResponseField name="roa" type="number">
      Return on Assets percentage
    </ResponseField>

    <ResponseField name="debtToEquity" type="number">
      Debt-to-Equity ratio
    </ResponseField>

    <ResponseField name="currentRatio" type="number">
      Current assets to current liabilities ratio
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="analystData" type="object">
  Analyst recommendations and targets

  <Expandable title="Analyst Data">
    <ResponseField name="recommendationMean" type="number">
      Average recommendation (1=Strong Buy, 5=Strong Sell)
    </ResponseField>

    <ResponseField name="recommendationKey" type="string">
      Text representation of recommendation
    </ResponseField>

    <ResponseField name="numberOfAnalystOpinions" type="number">
      Number of analysts covering the stock
    </ResponseField>

    <ResponseField name="targetHighPrice" type="number">
      Highest analyst price target
    </ResponseField>

    <ResponseField name="targetLowPrice" type="number">
      Lowest analyst price target
    </ResponseField>

    <ResponseField name="targetMeanPrice" type="number">
      Average analyst price target
    </ResponseField>

    <ResponseField name="targetMedianPrice" type="number">
      Median analyst price target
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="timestamp" type="string">
  Response timestamp in ISO format
</ResponseField>

## Example Response

<CodeGroup>
  ```json Apple Inc. (AAPL) theme={null}
  {
    "symbol": "AAPL",
    "companyName": "Apple Inc.",
    "industry": "Consumer Electronics",
    "sector": "Technology",
    "marketCap": 3120000000000,
    "employees": 164000,
    "description": "Apple Inc. designs, manufactures, and markets smartphones, personal computers, tablets, wearables, and accessories worldwide. The company serves consumers, and small and mid-sized businesses; and the education, enterprise, and government markets.",
    "website": "https://www.apple.com",
    "headquarters": "Cupertino, CA",
    "founded": "1976",
    "ceo": "Timothy D. Cook",
    "exchange": "NASDAQ",
    "financialMetrics": {
      "peRatio": 29.85,
      "pegRatio": 2.41,
      "priceToBook": 45.67,
      "priceToSales": 7.98,
      "dividendYield": 0.44,
      "beta": 1.29,
      "eps": 6.73,
      "revenue": 391035000000,
      "grossMargin": 0.4413,
      "operatingMargin": 0.2887,
      "netMargin": 0.2531,
      "roe": 1.4740,
      "roa": 0.2865,
      "debtToEquity": 1.96,
      "currentRatio": 0.93
    },
    "analystData": {
      "recommendationMean": 2.0,
      "recommendationKey": "buy",
      "numberOfAnalystOpinions": 38,
      "targetHighPrice": 250.0,
      "targetLowPrice": 180.0,
      "targetMeanPrice": 220.5,
      "targetMedianPrice": 225.0
    },
    "timestamp": "2025-06-28T18:42:12.471731"
  }
  ```

  ```json Microsoft Corp (MSFT) theme={null}
  {
    "symbol": "MSFT",
    "companyName": "Microsoft Corporation",
    "industry": "Software—Infrastructure",
    "sector": "Technology",
    "marketCap": 2890000000000,
    "employees": 221000,
    "description": "Microsoft Corporation develops, licenses, and supports software, services, devices, and solutions worldwide. The company operates in three segments: Productivity and Business Processes, Intelligent Cloud, and More Personal Computing.",
    "website": "https://www.microsoft.com",
    "headquarters": "Redmond, WA",
    "founded": "1975",
    "ceo": "Satya Nadella",
    "exchange": "NASDAQ",
    "financialMetrics": {
      "peRatio": 32.12,
      "pegRatio": 1.89,
      "priceToBook": 12.45,
      "priceToSales": 11.23,
      "dividendYield": 0.72,
      "beta": 0.91,
      "eps": 12.05,
      "revenue": 211915000000,
      "grossMargin": 0.6897,
      "operatingMargin": 0.4204,
      "netMargin": 0.3651,
      "roe": 0.4321,
      "roa": 0.1876,
      "debtToEquity": 0.47,
      "currentRatio": 1.77
    },
    "analystData": {
      "recommendationMean": 1.8,
      "recommendationKey": "buy",
      "numberOfAnalystOpinions": 42,
      "targetHighPrice": 480.0,
      "targetLowPrice": 350.0,
      "targetMeanPrice": 415.2,
      "targetMedianPrice": 420.0
    },
    "timestamp": "2025-06-28T18:42:12.471731"
  }
  ```
</CodeGroup>

## Error Responses

<CodeGroup>
  ```json Invalid Symbol theme={null}
  {
    "error": "Invalid symbol",
    "message": "Symbol 'INVALID' not found",
    "code": 404
  }
  ```

  ```json Rate Limit Exceeded theme={null}
  {
    "error": "Rate limit exceeded",
    "message": "Too many requests. Please try again later.",
    "code": 429,
    "retryAfter": 60
  }
  ```

  ```json Server Error theme={null}
  {
    "error": "Internal server error",
    "message": "Unable to fetch company data",
    "code": 500
  }
  ```
</CodeGroup>

## Use Cases

<AccordionGroup>
  <Accordion title="Investment Research">
    Get comprehensive company information for fundamental analysis:

    ```python theme={null}
    # Research Apple's fundamentals
    response = requests.get("https://api.example.com/api/v1/stock/AAPL/overview")
    data = response.json()

    # Check valuation metrics
    pe_ratio = data["financialMetrics"]["peRatio"]
    price_to_book = data["financialMetrics"]["priceToBook"]

    # Analyst sentiment
    recommendation = data["analystData"]["recommendationKey"]
    target_price = data["analystData"]["targetMeanPrice"]
    ```
  </Accordion>

  <Accordion title="Portfolio Analysis">
    Analyze holdings across different sectors and industries:

    ```python theme={null}
    portfolio = ["AAPL", "MSFT", "GOOGL", "TSLA"]
    sector_allocation = {}

    for symbol in portfolio:
        overview = get_stock_overview(symbol)
        sector = overview["sector"]
        sector_allocation[sector] = sector_allocation.get(sector, 0) + 1
    ```
  </Accordion>

  <Accordion title="Screening & Filtering">
    Filter stocks based on financial metrics:

    ```python theme={null}
    def screen_stocks(symbols, min_pe=None, max_pe=None, min_roe=None):
        filtered_stocks = []
        
        for symbol in symbols:
            overview = get_stock_overview(symbol)
            metrics = overview["financialMetrics"]
            
            if min_pe and metrics["peRatio"] < min_pe:
                continue
            if max_pe and metrics["peRatio"] > max_pe:
                continue
            if min_roe and metrics["roe"] < min_roe:
                continue
                
            filtered_stocks.append(symbol)
        
        return filtered_stocks
    ```
  </Accordion>

  <Accordion title="Company Comparison">
    Compare multiple companies side by side:

    ```python theme={null}
    def compare_companies(symbols):
        comparison = {}
        
        for symbol in symbols:
            overview = get_stock_overview(symbol)
            comparison[symbol] = {
                "name": overview["companyName"],
                "sector": overview["sector"],
                "market_cap": overview["marketCap"],
                "pe_ratio": overview["financialMetrics"]["peRatio"],
                "roe": overview["financialMetrics"]["roe"],
                "recommendation": overview["analystData"]["recommendationKey"]
            }
        
        return comparison
    ```
  </Accordion>
</AccordionGroup>

## Rate Limits

<Info>
  This endpoint is subject to the same rate limits as other stock data endpoints:

  * **YFinance**: No official limits, but may be rate limited by Yahoo Finance
  * **FMP**: Based on your plan (250-10,000+ requests per day)
</Info>

## Data Sources

<CardGroup cols={2}>
  <Card title="Primary: YFinance" icon="python">
    * Comprehensive company information
    * Financial metrics and ratios
    * Analyst recommendations
    * Real-time data updates
  </Card>

  <Card title="Fallback: FMP" icon="chart-line">
    * Professional-grade data
    * Consistent API structure
    * Additional financial metrics
    * Reliable uptime
  </Card>
</CardGroup>

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Stock Quote" icon="dollar-sign" href="/api-reference/stock/quote">
    Get real-time price and basic information
  </Card>

  <Card title="Historical Data" icon="chart-line" href="/api-reference/stock/historical">
    Access historical price and volume data
  </Card>

  <Card title="Financial Statements" icon="file-text" href="/api-reference/fmp/financials">
    Detailed income, balance sheet, and cash flow
  </Card>

  <Card title="Key Metrics" icon="calculator" href="/api-reference/fmp/metrics">
    Advanced financial ratios and metrics
  </Card>
</CardGroup>