# MetricDuck API - Complete Reference Documentation

**Base URL:** `https://api.metricduck.com`

---

## Table of Contents

1. [Introduction](#introduction)
2. [Authentication](#authentication)
3. [Rate Limiting](#rate-limiting)
4. [Response Format](#response-format)
5. [Error Handling](#error-handling)
6. [API Endpoints](#api-endpoints)
   - [Company Search & Metadata](#company-search--metadata)
   - [Financial Statements](#financial-statements)
   - [Metrics & Ratios](#metrics--ratios)
   - [Screener](#screener)
   - [Earnings & Insights](#earnings--insights)
   - [Market Data](#market-data)
7. [Common Use Cases](#common-use-cases)
8. [Code Examples](#code-examples)

---

## Introduction

MetricDuck provides institutional-grade financial data. Fundamentals, financial statements, signals, and XBRL facts are extracted directly from official SEC submissions (10-K, 10-Q, 8-K), ensuring accuracy and completeness; daily end-of-day stock prices (used for valuation multiples and returns) are sourced from a market-data feed.

### Key Features
- **Direct SEC Source:** Raw XBRL parsing from SEC EDGAR
- **10+ Years History:** Quarterly and annual data back to 2013+
- **5,500+ Companies:** US public companies filing with the SEC
- **250+ Metrics:** Comprehensive financial metrics and ratios
- **Daily Updates:** Fundamentals and filing text updated daily from SEC EDGAR; end-of-day prices

---

## Authentication

All API requests require an API key passed in the `X-API-Key` header.

### Getting Your API Key
1. Sign up at https://metricduck.com
2. Navigate to Dashboard → API Keys
3. Generate new API key
4. Include in all requests

### Example Request
```bash
curl -H "X-API-Key: your_api_key_here" \
  https://api.metricduck.com/api/v1/companies/AAPL/overview-page
```

---

## Rate Limiting

Rate limits are enforced per subscription tier and returned in response headers.

### Subscription Tiers

| Tier | Credits | Price |
|------|---------|-------|
| **Free** | 500/day (resets midnight UTC) | $0 |
| **Pro** | No daily cap · 50,000/month | $20/month ($200/year) |

Need more than 50,000 credits/month? Email support@metricduck.com.

### Rate Limit Headers
`X-RateLimit-*` are not the daily allowance. Where an endpoint has a per-minute limiter they
describe your plan's **per-minute** limit (the reset is a Unix timestamp); some older endpoints
still send a legacy request counter in them. Per-minute example:
```
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 47
X-RateLimit-Reset: 1793318460
```
The free daily allowance is not sent as a header. A call past it is refused with HTTP 429,
`"error_code": "FREE_DAILY_CAP"`, `limit` (the day's limit that was reached),
`resets_at` (the next 00:00 UTC) and a `Retry-After` header.

### Guest Mode (No Authentication)
- **5 requests per day** (IP-based)
- Access to all endpoints (limited requests)
- Headers: `X-Trial-Mode: true`, `X-User-Type: guest`

---

## Response Format

All endpoints return JSON with consistent structure:

### Success Response
```json
{
  "ticker": "AAPL",
  "company_name": "Apple Inc.",
  "data": {
    // Endpoint-specific data
  },
  "metadata": {
    "last_updated": "2024-11-01T12:00:00Z",
    "source": "SEC 10-K",
    "filing_date": "2024-10-31"
  }
}
```

### List Response
```json
[
  {
    "ticker": "AAPL",
    "company_name": "Apple Inc.",
    // ... data fields
  },
  {
    "ticker": "MSFT",
    "company_name": "Microsoft Corporation",
    // ... data fields
  }
]
```

---

## Error Handling

### Error Response Format
```json
{
  "detail": "Ticker 'INVALID' not found",
  "error_code": "TICKER_NOT_FOUND",
  "status_code": 404
}
```

### Common Error Codes

| HTTP Code | Error Code | Description |
|-----------|------------|-------------|
| 400 | INVALID_PARAMETER | Invalid query parameter |
| 401 | UNAUTHORIZED | Missing or invalid API key |
| 404 | TICKER_NOT_FOUND | Company ticker not found |
| 404 | DATA_NOT_FOUND | No data available for request |
| 429 | RATE_LIMIT_EXCEEDED | Rate limit exceeded |
| 500 | INTERNAL_SERVER_ERROR | Server error |

---

## API Endpoints

### Company Search & Metadata

#### 1. Search Companies
**Endpoint:** `GET /api/v1/companies/search`

Search for companies by name or ticker with fuzzy matching.

**Query Parameters:**
- `query` (required): Search query (company name or ticker)
- `limit` (optional): Max results (default: 20, max: 100)

**Example Request:**
```bash
GET /api/v1/companies/search?query=apple&limit=5
```

**Example Response:**
```json
[
  {
    "ticker": "AAPL",
    "company_name": "Apple Inc.",
    "cik": "0000320193",
    "exchange": "NASDAQ",
    "sector": "Technology",
    "industry": "Consumer Electronics",
    "market_cap": 2800000000000
  },
  {
    "ticker": "APLE",
    "company_name": "Apple Hospitality REIT Inc.",
    "cik": "0001418121",
    "exchange": "NYSE",
    "sector": "Real Estate",
    "industry": "REIT - Hotel & Motel",
    "market_cap": 3200000000
  }
]
```

---

#### 2. Company Overview
**Endpoint:** `GET /api/v1/companies/{ticker}/overview-page`

Get comprehensive financial snapshot for a company.

**Path Parameters:**
- `ticker` (required): Company ticker symbol (e.g., "AAPL")

**Example Request:**
```bash
GET /api/v1/companies/AAPL/overview-page
```

**Example Response:**
```json
{
  "ticker": "AAPL",
  "company_name": "Apple Inc.",
  "cik": "0000320193",
  "sector": "Technology",
  "industry": "Consumer Electronics",

  "valuation": {
    "market_cap": 2800000000000,
    "enterprise_value": 2750000000000,
    "pe_ratio": 28.5,
    "pb_ratio": 42.1,
    "ps_ratio": 7.2,
    "ev_sales": 7.0,
    "ev_ebitda": 22.3
  },

  "profitability": {
    "revenue": 394328000000,
    "revenue_growth_yoy": 0.078,
    "net_income": 96995000000,
    "net_margin": 0.246,
    "gross_margin": 0.458,
    "operating_margin": 0.302,
    "roe": 1.47,
    "roa": 0.287,
    "roic": 0.545
  },

  "cash_flow": {
    "operating_cash_flow": 110543000000,
    "free_cash_flow": 99584000000,
    "fcf_margin": 0.252,
    "capex": 10959000000
  },

  "balance_sheet": {
    "total_assets": 364980000000,
    "total_liabilities": 290437000000,
    "total_equity": 74543000000,
    "total_debt": 106628000000,
    "cash": 61555000000,
    "current_ratio": 1.04,
    "quick_ratio": 0.87,
    "debt_to_equity": 1.43,
    "debt_to_assets": 0.292
  },

  "metadata": {
    "last_filing_date": "2024-10-31",
    "fiscal_year_end": "2024-09-28",
    "period": "FY 2024",
    "source": "SEC 10-K"
  }
}
```

---

### Financial Statements

#### 3. Income Statement
**Endpoint:** `GET /api/v1/companies/{ticker}/income-statement`

Get multi-period income statement data.

**Path Parameters:**
- `ticker` (required): Company ticker symbol

**Query Parameters:**
- `period` (optional): "quarterly", "annual", or "ttm" (default: "quarterly")
- `years` (optional): Number of years of history (default: 5, max: 10)
- `include_segment_hierarchy` (optional): Include hierarchical segment breakdown (default: false)

**Example Request:**
```bash
GET /api/v1/companies/AAPL/income-statement?period=quarterly&years=2
```

**Example Response:**
```json
[
  {
    "ticker": "AAPL",
    "company_name": "Apple Inc.",
    "period_end_date": "2024-09-28",
    "fiscal_period": "Q4 2024",
    "period_type": "quarterly",

    "revenue": 94930000000,
    "cost_of_revenue": 52299000000,
    "gross_profit": 42631000000,
    "gross_margin": 0.449,

    "operating_expenses": 14105000000,
    "research_development": 7709000000,
    "sga": 6396000000,

    "operating_income": 28526000000,
    "operating_margin": 0.301,
    "ebit": 28526000000,
    "ebitda": 31245000000,

    "interest_expense": 923000000,
    "interest_income": 1055000000,
    "other_income_expense": 123000000,

    "pretax_income": 28781000000,
    "income_tax": 4494000000,
    "effective_tax_rate": 0.156,

    "net_income": 24287000000,
    "net_margin": 0.256,

    "eps_basic": 1.52,
    "eps_diluted": 1.51,
    "shares_basic": 15958000000,
    "shares_diluted": 16066000000
  },
  {
    "ticker": "AAPL",
    "period_end_date": "2024-06-29",
    "fiscal_period": "Q3 2024",
    // ... similar structure
  }
  // ... more periods
]
```

**Data Fields:**

**Revenue & Costs:**
- `revenue`: Total sales/revenue
- `cost_of_revenue`: Cost of goods sold (COGS)
- `gross_profit`: Revenue - COGS
- `gross_margin`: Gross profit / Revenue

**Operating Expenses:**
- `operating_expenses`: Total operating expenses
- `research_development`: R&D expenses
- `sga`: Selling, general & administrative expenses

**Profitability:**
- `operating_income`: Gross profit - Operating expenses
- `operating_margin`: Operating income / Revenue
- `ebit`: Earnings before interest & taxes
- `ebitda`: EBIT + Depreciation & Amortization

**Bottom Line:**
- `net_income`: Net profit after all expenses
- `net_margin`: Net income / Revenue
- `eps_basic`: Earnings per share (basic)
- `eps_diluted`: Earnings per share (diluted)

---

#### 4. Balance Sheet
**Endpoint:** `GET /api/v1/companies/{ticker}/balance-sheet`

Get multi-period balance sheet data.

**Path Parameters:**
- `ticker` (required): Company ticker symbol

**Query Parameters:**
- `period` (optional): "quarterly" or "annual" (default: "quarterly")
- `years` (optional): Number of years of history (default: 5, max: 10)

**Example Request:**
```bash
GET /api/v1/companies/AAPL/balance-sheet?period=quarterly&years=2
```

**Example Response:**
```json
[
  {
    "ticker": "AAPL",
    "company_name": "Apple Inc.",
    "period_end_date": "2024-09-28",
    "fiscal_period": "Q4 2024",
    "period_type": "quarterly",

    "assets": {
      "total_assets": 364980000000,
      "current_assets": 143566000000,
      "cash_and_equivalents": 29943000000,
      "marketable_securities": 31590000000,
      "accounts_receivable": 26453000000,
      "inventory": 6511000000,
      "other_current_assets": 14831000000,

      "noncurrent_assets": 221414000000,
      "ppe_net": 44111000000,
      "intangibles": 0,
      "goodwill": 0,
      "other_noncurrent_assets": 177303000000
    },

    "liabilities": {
      "total_liabilities": 290437000000,
      "current_liabilities": 137879000000,
      "accounts_payable": 58239000000,
      "accrued_expenses": 45782000000,
      "deferred_revenue": 8249000000,
      "current_debt": 10912000000,
      "other_current_liabilities": 14697000000,

      "noncurrent_liabilities": 152558000000,
      "long_term_debt": 95716000000,
      "deferred_tax_liabilities": 17181000000,
      "other_noncurrent_liabilities": 39661000000
    },

    "equity": {
      "total_equity": 74543000000,
      "common_stock": 82689000000,
      "retained_earnings": 19574000000,
      "treasury_stock": -72952000000,
      "other_equity": -14768000000
    },

    "ratios": {
      "current_ratio": 1.04,
      "quick_ratio": 0.87,
      "debt_to_equity": 1.43,
      "debt_to_assets": 0.292,
      "working_capital": 5687000000
    }
  }
  // ... more periods
]
```

**Data Fields:**

**Assets:**
- `total_assets`: All assets (current + noncurrent)
- `current_assets`: Assets convertible to cash within 1 year
- `cash_and_equivalents`: Cash, bank deposits
- `marketable_securities`: Short-term investments
- `accounts_receivable`: Money owed by customers
- `inventory`: Unsold products
- `ppe_net`: Property, plant & equipment (net of depreciation)
- `intangibles`: Patents, trademarks, software
- `goodwill`: Acquisition premium

**Liabilities:**
- `total_liabilities`: All obligations (current + noncurrent)
- `current_liabilities`: Due within 1 year
- `accounts_payable`: Money owed to suppliers
- `current_debt`: Debt due within 1 year
- `long_term_debt`: Debt due beyond 1 year
- `deferred_revenue`: Unearned revenue

**Equity:**
- `total_equity`: Shareholder equity (Assets - Liabilities)
- `retained_earnings`: Cumulative net income retained
- `treasury_stock`: Buyback stock (negative value)

**Ratios:**
- `current_ratio`: Current assets / Current liabilities
- `quick_ratio`: (Current assets - Inventory) / Current liabilities
- `debt_to_equity`: Total debt / Total equity
- `debt_to_assets`: Total debt / Total assets

---

#### 5. Cash Flow Statement
**Endpoint:** `GET /api/v1/companies/{ticker}/cash-flow`

Get multi-period cash flow statement data.

**Path Parameters:**
- `ticker` (required): Company ticker symbol

**Query Parameters:**
- `period` (optional): "quarterly" or "annual" (default: "quarterly")
- `years` (optional): Number of years of history (default: 5, max: 10)

**Example Request:**
```bash
GET /api/v1/companies/AAPL/cash-flow?period=quarterly&years=2
```

**Example Response:**
```json
[
  {
    "ticker": "AAPL",
    "company_name": "Apple Inc.",
    "period_end_date": "2024-09-28",
    "fiscal_period": "Q4 2024",
    "period_type": "quarterly",

    "operating_activities": {
      "operating_cash_flow": 30634000000,
      "net_income": 24287000000,
      "depreciation_amortization": 2719000000,
      "stock_based_compensation": 2445000000,
      "change_working_capital": 1183000000,
      "change_accounts_receivable": -5423000000,
      "change_inventory": -1294000000,
      "change_accounts_payable": 7900000000
    },

    "investing_activities": {
      "investing_cash_flow": -7543000000,
      "capex": -2959000000,
      "acquisitions": 0,
      "marketable_securities_purchased": -31900000000,
      "marketable_securities_sold": 27316000000
    },

    "financing_activities": {
      "financing_cash_flow": -24371000000,
      "dividends_paid": -3826000000,
      "stock_repurchased": -24347000000,
      "debt_issued": 5250000000,
      "debt_repaid": -1450000000
    },

    "net_change_cash": -1280000000,
    "cash_beginning": 31223000000,
    "cash_ending": 29943000000,

    "derived_metrics": {
      "free_cash_flow": 27675000000,
      "fcf_margin": 0.292,
      "cash_conversion": 1.14
    }
  }
  // ... more periods
]
```

**Data Fields:**

**Operating Activities:**
- `operating_cash_flow`: Cash from core business operations
- `net_income`: Starting point for cash flow calculation
- `depreciation_amortization`: Non-cash expense add-back
- `change_working_capital`: Change in current assets/liabilities

**Investing Activities:**
- `investing_cash_flow`: Cash from investments
- `capex`: Capital expenditures (PP&E purchases)
- `acquisitions`: Business acquisitions
- `marketable_securities_purchased/sold`: Investment activity

**Financing Activities:**
- `financing_cash_flow`: Cash from financing
- `dividends_paid`: Cash dividends to shareholders
- `stock_repurchased`: Stock buybacks
- `debt_issued/repaid`: Debt activity

**Derived Metrics:**
- `free_cash_flow`: Operating cash flow - Capex
- `fcf_margin`: Free cash flow / Revenue
- `cash_conversion`: Operating cash flow / Net income

---

### Metrics & Ratios

#### 6. Available Metrics
**Endpoint:** `GET /api/v1/metrics`

Get catalog of all available financial metrics.

**Example Request:**
```bash
GET /api/v1/metrics
```

**Example Response:**
```json
[
  {
    "metric_id": "revenue",
    "display_name": "Revenue",
    "description": "Total sales and service revenue",
    "category": "Income Statement",
    "subcategory": "Revenue",
    "unit": "currency",
    "format": "number"
  },
  {
    "metric_id": "net_income",
    "display_name": "Net Income",
    "description": "Bottom-line profit after all expenses",
    "category": "Income Statement",
    "subcategory": "Profitability",
    "unit": "currency",
    "format": "number"
  },
  {
    "metric_id": "pe_ratio",
    "display_name": "P/E Ratio",
    "description": "Price-to-earnings ratio (TTM)",
    "category": "Valuation",
    "subcategory": "Multiples",
    "unit": "ratio",
    "format": "decimal"
  }
  // ... 250+ metrics in total
]
```

---

#### 7. Company Ratios
**Endpoint:** `GET /api/v1/companies/{ticker}/ratios`

Get financial ratios for a company.

**Path Parameters:**
- `ticker` (required): Company ticker symbol

**Query Parameters:**
- `period` (optional): "quarterly" or "annual" (default: "quarterly")
- `years` (optional): Number of years of history (default: 5, max: 10)

**Example Request:**
```bash
GET /api/v1/companies/AAPL/ratios?period=quarterly&years=2
```

**Example Response:**
```json
[
  {
    "ticker": "AAPL",
    "period_end_date": "2024-09-28",
    "fiscal_period": "Q4 2024",

    "profitability_ratios": {
      "gross_margin": 0.449,
      "operating_margin": 0.301,
      "net_margin": 0.256,
      "roe": 1.47,
      "roa": 0.287,
      "roic": 0.545
    },

    "liquidity_ratios": {
      "current_ratio": 1.04,
      "quick_ratio": 0.87,
      "cash_ratio": 0.45
    },

    "leverage_ratios": {
      "debt_to_equity": 1.43,
      "debt_to_assets": 0.292,
      "equity_multiplier": 4.89,
      "interest_coverage": 30.9
    },

    "efficiency_ratios": {
      "asset_turnover": 1.08,
      "inventory_turnover": 60.6,
      "receivables_turnover": 14.9,
      "days_sales_outstanding": 24.5,
      "days_inventory_outstanding": 6.0
    },

    "valuation_ratios": {
      "pe_ratio": 28.5,
      "pb_ratio": 42.1,
      "ps_ratio": 7.2,
      "ev_sales": 7.0,
      "ev_ebitda": 22.3,
      "peg_ratio": 3.6
    }
  }
  // ... more periods
]
```

---

#### 8. Custom Metrics Query
**Endpoint:** `GET /api/v1/data/metrics`

Query specific metrics for multiple companies in one call.

**Query Parameters:**
- `tickers` (required): Comma-separated tickers (e.g., `AAPL,MSFT,GOOGL`)
- `metrics` (required): Comma-separated metric IDs (e.g., `revenues,roic,roe`)
- `period` (optional): `ttm`, `quarterly`, or `annual` (default: `ttm`)
- `years` (optional): Years of history, 1-10 (default: 2)
- `dimensions` (optional): Compound period types for trend/statistical analysis
  (e.g., `Q.TREND8,Q.MED8,TTM.YOY`)
- `price` (optional): `historical` (period-end) or `current` (default: `historical`)

**Example Requests:**
```bash
GET /api/v1/data/metrics?tickers=AAPL,MSFT,GOOGL&metrics=revenues,roic,roe&period=ttm&years=2
GET /api/v1/data/metrics?tickers=AAPL&metrics=roic&period=quarterly&dimensions=Q.TREND8,Q.MED8
```

---

### Screener

#### 9. Screen Companies
**Endpoint:** `POST /api/v1/screener/screen`

Screen companies based on financial criteria.

**Request Body:**
```json
{
  "filters": [
    {
      "metric_id": "pe_ratio",
      "period_type": "ttm",
      "operator": "between",
      "min_value": 10,
      "max_value": 25
    },
    {
      "metric_id": "roe",
      "period_type": "ttm",
      "operator": "gte",
      "value": 0.15
    },
    {
      "metric_id": "revenue",
      "period_type": "ttm",
      "operator": "gte",
      "value": 1000000000
    }
  ],
  "sectors": ["TECH", "HEALTH"],
  "include_metrics": ["revenue", "net_income", "pe_ratio", "roe", "market_cap"],
  "limit": 20,
  "sort_by": "market_cap",
  "sort_order": "desc"
}
```

**Filter Operators:**
- `lt`: Less than
- `lte`: Less than or equal
- `gt`: Greater than
- `gte`: Greater than or equal
- `eq`: Equal to
- `between`: Between min_value and max_value

**Period Types:**
- `ttm`: Trailing twelve months
- `q`: Most recent quarter
- `fy`: Most recent fiscal year
- `ss`: Same season (Q1→Q1, Q2→Q2, etc.)
- Growth: `ttm.yoy`, `ttm.cagr3`, `ss.yoy`

**Example Response:**
```json
{
  "total_count": 47,
  "returned_count": 20,
  "filters_applied": 3,
  "results": [
    {
      "ticker": "AAPL",
      "company_name": "Apple Inc.",
      "sector": "Technology",
      "industry": "Consumer Electronics",
      "metrics": {
        "revenue": 394328000000,
        "net_income": 96995000000,
        "pe_ratio": 28.5,
        "roe": 1.47,
        "market_cap": 2800000000000
      }
    },
    {
      "ticker": "MSFT",
      "company_name": "Microsoft Corporation",
      "sector": "Technology",
      "industry": "Software - Infrastructure",
      "metrics": {
        "revenue": 245122000000,
        "net_income": 88136000000,
        "pe_ratio": 32.1,
        "roe": 0.42,
        "market_cap": 3100000000000
      }
    }
    // ... more companies
  ]
}
```

---

#### 10. Get Screener Metrics
**Endpoint:** `GET /api/v1/screener/metrics`

Get list of metrics available for screening with metadata.

**Example Response:**
```json
[
  {
    "metric_id": "pe_ratio",
    "display_name": "P/E Ratio",
    "category": "Valuation",
    "available_periods": ["ttm", "fy"],
    "supports_growth": false,
    "unit": "ratio"
  },
  {
    "metric_id": "revenue",
    "display_name": "Revenue",
    "category": "Income Statement",
    "available_periods": ["ttm", "q", "fy", "ss"],
    "supports_growth": true,
    "unit": "currency"
  }
  // ... more metrics
]
```

---

### Earnings & Insights

#### 11. Earnings Insights
**Endpoint:** `GET /api/v1/earnings/{ticker}/latest`

Latest 8-K earnings-release figures for a company, extracted from the release
itself — typically weeks before the audited 10-Q/10-K is filed. Each figure
carries a receipt (a verbatim quote and a deep link into the source exhibit)
where one has been attested.

**Path Parameters:**
- `ticker` (required): Company ticker symbol, or a 10-digit CIK

**Example Request:**
```bash
GET /api/v1/earnings/AAPL/latest
```

**Related:** `GET /api/v1/earnings/{ticker}/history?quarters=8` for several
quarters of the same data.

---


### Market Data

#### 12. Company Peers
**Endpoint:** `GET /api/v1/peers/{cik_or_ticker}`

Get comparable companies in same sector/industry.

**Path Parameters:**
- `cik_or_ticker` (required): Company ticker or CIK

**Query Parameters:**
- `tickers` (optional): Comma-separated peer tickers (e.g. `AAPL,GOOGL,META`). If provided, used instead of auto-selection.
- `peer_mode` (optional): `tags` uses Jaccard similarity on business-model tags. Default uses sector + market-cap range.
- `metrics` (optional): Comma-separated metric_ids to render instead of the default curated table. A confident near-miss (`operating_margin`) is read as the served id and listed in `metadata.resolved_metrics`; any other unknown id is listed in `metadata.ignored_metrics` with its closest ids.

**Example Request:**
```bash
GET /api/v1/peers/AAPL
```

**Example Response:**
```json
{
  "ticker": "AAPL",
  "company_name": "Apple Inc.",
  "sector": "Technology",
  "industry": "Consumer Electronics",

  "peers": [
    {
      "ticker": "MSFT",
      "company_name": "Microsoft Corporation",
      "sector": "Technology",
      "industry": "Software - Infrastructure",
      "market_cap": 3100000000000,
      "similarity_score": 0.85
    },
    {
      "ticker": "GOOGL",
      "company_name": "Alphabet Inc.",
      "sector": "Technology",
      "industry": "Internet Content & Information",
      "market_cap": 1900000000000,
      "similarity_score": 0.82
    }
    // ... more peers
  ]
}
```

---

#### 13. Sectors & Industries
**Endpoint:** `GET /api/v1/sectors`

Get list of all sectors and industries with company counts.

**Example Response:**
```json
[
  {
    "sector_code": "TECH",
    "sector_name": "Technology",
    "company_count": 1247,
    "industries": [
      {
        "industry_code": "TECH_SOFTWARE",
        "industry_name": "Software - Infrastructure",
        "company_count": 342
      },
      {
        "industry_code": "TECH_HARDWARE",
        "industry_name": "Consumer Electronics",
        "company_count": 89
      }
      // ... more industries
    ]
  },
  {
    "sector_code": "HEALTH",
    "sector_name": "Healthcare",
    "company_count": 876,
    "industries": [
      {
        "industry_code": "HEALTH_PHARMA",
        "industry_name": "Drug Manufacturers",
        "company_count": 234
      }
      // ... more industries
    ]
  }
  // ... more sectors
]
```

---

## Common Use Cases

### 1. Find Undervalued Companies
```bash
# Screen for low P/E, high ROE companies
POST /api/v1/screener/screen
{
  "filters": [
    {"metric_id": "pe_ratio", "period_type": "ttm", "operator": "lt", "value": 15},
    {"metric_id": "roe", "period_type": "ttm", "operator": "gte", "value": 0.20},
    {"metric_id": "debt_to_equity", "period_type": "q", "operator": "lt", "value": 0.5}
  ],
  "sort_by": "pe_ratio",
  "sort_order": "asc"
}
```

### 2. Track Profitability Trends
```bash
# Get 5 years of quarterly income statements
GET /api/v1/companies/AAPL/income-statement?period=quarterly&years=5

# Calculate margin trends over time
```

### 3. Compare Peer Performance
```bash
# Step 1: Find peers
GET /api/v1/peers/AAPL

# Step 2: Query metrics for all peers in one call
GET /api/v1/data/metrics?tickers=AAPL,MSFT,GOOGL,META&metrics=revenues,net_margin,roe,roic&period=ttm
```

### 4. Monitor Earnings Releases
```bash
# Latest earnings release for a company
GET /api/v1/earnings/{ticker}/latest

# Or walk back several quarters
GET /api/v1/earnings/{ticker}/history?quarters=8
```

---

## Code Examples

### Python
```python
import requests

API_KEY = "your_api_key_here"
BASE_URL = "https://api.metricduck.com"

headers = {"X-API-Key": API_KEY}

# Search for companies
response = requests.get(
    f"{BASE_URL}/api/v1/companies/search",
    params={"q": "apple", "limit": 5},
    headers=headers
)
companies = response.json()

# Get company overview
ticker = "AAPL"
response = requests.get(
    f"{BASE_URL}/api/v1/companies/{ticker}/overview-page",
    headers=headers
)
overview = response.json()
print(f"PE Ratio: {overview['valuation']['pe_ratio']}")
print(f"ROE: {overview['profitability']['roe']}")

# Screen companies
screen_request = {
    "filters": [
        {"metric_id": "pe_ratio", "period_type": "ttm", "operator": "lt", "value": 20},
        {"metric_id": "roe", "period_type": "ttm", "operator": "gte", "value": 0.15}
    ],
    "limit": 20
}
response = requests.post(
    f"{BASE_URL}/api/v1/screener/screen",
    json=screen_request,
    headers=headers
)
results = response.json()
```

### JavaScript/Node.js
```javascript
const axios = require('axios');

const API_KEY = 'your_api_key_here';
const BASE_URL = 'https://api.metricduck.com';

const headers = { 'X-API-Key': API_KEY };

// Get income statement
async function getIncomeStatement(ticker) {
  const response = await axios.get(
    `${BASE_URL}/api/v1/companies/${ticker}/income-statement`,
    {
      params: { period: 'quarterly', years: 2 },
      headers
    }
  );
  return response.data;
}

// Screen companies
async function screenCompanies(filters) {
  const response = await axios.post(
    `${BASE_URL}/api/v1/screener/screen`,
    {
      filters,
      limit: 20,
      sort_by: 'market_cap',
      sort_order: 'desc'
    },
    { headers }
  );
  return response.data;
}
```

### cURL
```bash
# Search companies
curl -H "X-API-Key: your_api_key" \
  "https://api.metricduck.com/api/v1/companies/search?query=apple&limit=5"

# Get overview
curl -H "X-API-Key: your_api_key" \
  "https://api.metricduck.com/api/v1/companies/AAPL/overview-page"

# Screen companies
curl -X POST \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [
      {"metric_id": "pe_ratio", "period_type": "ttm", "operator": "lt", "value": 20}
    ],
    "limit": 20
  }' \
  "https://api.metricduck.com/api/v1/screener/screen"
```

---

## Additional Resources

- **OpenAPI Specification:** https://api.metricduck.com/openapi.json
- **Interactive Docs:** https://api.metricduck.com/docs
- **MCP Server:** https://github.com/metricduck/mcp-server
- **Support:** support@metricduck.com

---

**Built for AI systems, researchers, and financial professionals.**