|
|
"""
|
|
|
Data catalog endpoint
|
|
|
"""
|
|
|
|
|
|
from datetime import datetime
|
|
|
from typing import Dict, List
|
|
|
from fastapi import APIRouter, Depends
|
|
|
from sqlalchemy.ext.asyncio import AsyncSession
|
|
|
|
|
|
from app.core.database import get_db
|
|
|
from app.schemas.financial import DataCatalogResponse, DataCatalogItem
|
|
|
|
|
|
router = APIRouter()
|
|
|
|
|
|
def get_data_catalog() -> Dict[str, List[DataCatalogItem]]:
|
|
|
"""Get comprehensive data catalog"""
|
|
|
|
|
|
catalog = {
|
|
|
"Company Information": [
|
|
|
DataCatalogItem(
|
|
|
field_name="ticker",
|
|
|
description="Stock ticker symbol",
|
|
|
data_type="string",
|
|
|
unit=None,
|
|
|
calculation=None,
|
|
|
source="SEC EDGAR"
|
|
|
),
|
|
|
DataCatalogItem(
|
|
|
field_name="name",
|
|
|
description="Company legal name",
|
|
|
data_type="string",
|
|
|
unit=None,
|
|
|
calculation=None,
|
|
|
source="SEC EDGAR"
|
|
|
),
|
|
|
DataCatalogItem(
|
|
|
field_name="cik",
|
|
|
description="Central Index Key - SEC's unique identifier",
|
|
|
data_type="string",
|
|
|
unit=None,
|
|
|
calculation=None,
|
|
|
source="SEC EDGAR"
|
|
|
),
|
|
|
DataCatalogItem(
|
|
|
field_name="sector",
|
|
|
description="Business sector classification",
|
|
|
data_type="string",
|
|
|
unit=None,
|
|
|
calculation=None,
|
|
|
source="SEC EDGAR / External"
|
|
|
),
|
|
|
DataCatalogItem(
|
|
|
field_name="industry",
|
|
|
description="Industry classification",
|
|
|
data_type="string",
|
|
|
unit=None,
|
|
|
calculation=None,
|
|
|
source="SEC EDGAR / External"
|
|
|
)
|
|
|
],
|
|
|
|
|
|
"Income Statement": [
|
|
|
DataCatalogItem(
|
|
|
field_name="revenue",
|
|
|
description="Total revenue/sales for the period",
|
|
|
data_type="float",
|
|
|
unit="USD",
|
|
|
calculation=None,
|
|
|
source="SEC EDGAR 10-K/10-Q"
|
|
|
),
|
|
|
DataCatalogItem(
|
|
|
field_name="gross_profit",
|
|
|
description="Revenue minus cost of goods sold",
|
|
|
data_type="float",
|
|
|
unit="USD",
|
|
|
calculation="Revenue - COGS",
|
|
|
source="SEC EDGAR 10-K/10-Q"
|
|
|
),
|
|
|
DataCatalogItem(
|
|
|
field_name="operating_income",
|
|
|
description="Gross profit minus operating expenses",
|
|
|
data_type="float",
|
|
|
unit="USD",
|
|
|
calculation="Gross Profit - Operating Expenses",
|
|
|
source="SEC EDGAR 10-K/10-Q"
|
|
|
),
|
|
|
DataCatalogItem(
|
|
|
field_name="net_income",
|
|
|
description="Bottom line profit after all expenses and taxes",
|
|
|
data_type="float",
|
|
|
unit="USD",
|
|
|
calculation="Operating Income - Interest - Taxes",
|
|
|
source="SEC EDGAR 10-K/10-Q"
|
|
|
),
|
|
|
DataCatalogItem(
|
|
|
field_name="eps",
|
|
|
description="Earnings per share - basic",
|
|
|
data_type="float",
|
|
|
unit="USD per share",
|
|
|
calculation="Net Income / Shares Outstanding",
|
|
|
source="SEC EDGAR 10-K/10-Q"
|
|
|
)
|
|
|
],
|
|
|
|
|
|
"Balance Sheet": [
|
|
|
DataCatalogItem(
|
|
|
field_name="total_assets",
|
|
|
description="Total value of everything the company owns",
|
|
|
data_type="float",
|
|
|
unit="USD",
|
|
|
calculation="Current Assets + Non-Current Assets",
|
|
|
source="SEC EDGAR 10-K/10-Q"
|
|
|
),
|
|
|
DataCatalogItem(
|
|
|
field_name="total_equity",
|
|
|
description="Shareholders' equity (Assets - Liabilities)",
|
|
|
data_type="float",
|
|
|
unit="USD",
|
|
|
calculation="Total Assets - Total Liabilities",
|
|
|
source="SEC EDGAR 10-K/10-Q"
|
|
|
),
|
|
|
DataCatalogItem(
|
|
|
field_name="total_debt",
|
|
|
description="Long-term debt obligations",
|
|
|
data_type="float",
|
|
|
unit="USD",
|
|
|
calculation=None,
|
|
|
source="SEC EDGAR 10-K/10-Q"
|
|
|
),
|
|
|
DataCatalogItem(
|
|
|
field_name="cash",
|
|
|
description="Cash and cash equivalents",
|
|
|
data_type="float",
|
|
|
unit="USD",
|
|
|
calculation=None,
|
|
|
source="SEC EDGAR 10-K/10-Q"
|
|
|
),
|
|
|
DataCatalogItem(
|
|
|
field_name="shares_outstanding",
|
|
|
description="Number of shares currently held by shareholders",
|
|
|
data_type="float",
|
|
|
unit="shares",
|
|
|
calculation=None,
|
|
|
source="SEC EDGAR 10-K/10-Q"
|
|
|
)
|
|
|
],
|
|
|
|
|
|
"Cash Flow Statement": [
|
|
|
DataCatalogItem(
|
|
|
field_name="operating_cash_flow",
|
|
|
description="Cash generated from core business operations",
|
|
|
data_type="float",
|
|
|
unit="USD",
|
|
|
calculation="Net Income + Non-cash adjustments + Working Capital changes",
|
|
|
source="SEC EDGAR 10-K/10-Q"
|
|
|
),
|
|
|
DataCatalogItem(
|
|
|
field_name="free_cash_flow",
|
|
|
description="Cash available after capital expenditures",
|
|
|
data_type="float",
|
|
|
unit="USD",
|
|
|
calculation="Operating Cash Flow - Capital Expenditures",
|
|
|
source="SEC EDGAR 10-K/10-Q"
|
|
|
),
|
|
|
DataCatalogItem(
|
|
|
field_name="capex",
|
|
|
description="Capital expenditures for property, plant, and equipment",
|
|
|
data_type="float",
|
|
|
unit="USD",
|
|
|
calculation=None,
|
|
|
source="SEC EDGAR 10-K/10-Q"
|
|
|
)
|
|
|
],
|
|
|
|
|
|
"Valuation Ratios": [
|
|
|
DataCatalogItem(
|
|
|
field_name="pe_ratio",
|
|
|
description="Price-to-Earnings ratio (trailing)",
|
|
|
data_type="float",
|
|
|
unit="ratio",
|
|
|
calculation="Stock Price / EPS",
|
|
|
source="Calculated"
|
|
|
),
|
|
|
DataCatalogItem(
|
|
|
field_name="pb_ratio",
|
|
|
description="Price-to-Book ratio",
|
|
|
data_type="float",
|
|
|
unit="ratio",
|
|
|
calculation="Market Cap / Total Equity",
|
|
|
source="Calculated"
|
|
|
),
|
|
|
DataCatalogItem(
|
|
|
field_name="ps_ratio",
|
|
|
description="Price-to-Sales ratio",
|
|
|
data_type="float",
|
|
|
unit="ratio",
|
|
|
calculation="Market Cap / Revenue",
|
|
|
source="Calculated"
|
|
|
),
|
|
|
DataCatalogItem(
|
|
|
field_name="ev_ebitda",
|
|
|
description="Enterprise Value to EBITDA ratio",
|
|
|
data_type="float",
|
|
|
unit="ratio",
|
|
|
calculation="Enterprise Value / EBITDA",
|
|
|
source="Calculated"
|
|
|
)
|
|
|
],
|
|
|
|
|
|
"Profitability Metrics": [
|
|
|
DataCatalogItem(
|
|
|
field_name="roe",
|
|
|
description="Return on Equity",
|
|
|
data_type="float",
|
|
|
unit="percentage",
|
|
|
calculation="(Net Income / Total Equity) × 100",
|
|
|
source="Calculated"
|
|
|
),
|
|
|
DataCatalogItem(
|
|
|
field_name="roa",
|
|
|
description="Return on Assets",
|
|
|
data_type="float",
|
|
|
unit="percentage",
|
|
|
calculation="(Net Income / Total Assets) × 100",
|
|
|
source="Calculated"
|
|
|
),
|
|
|
DataCatalogItem(
|
|
|
field_name="gross_margin",
|
|
|
description="Gross profit margin",
|
|
|
data_type="float",
|
|
|
unit="percentage",
|
|
|
calculation="(Gross Profit / Revenue) × 100",
|
|
|
source="Calculated"
|
|
|
),
|
|
|
DataCatalogItem(
|
|
|
field_name="operating_margin",
|
|
|
description="Operating profit margin",
|
|
|
data_type="float",
|
|
|
unit="percentage",
|
|
|
calculation="(Operating Income / Revenue) × 100",
|
|
|
source="Calculated"
|
|
|
),
|
|
|
DataCatalogItem(
|
|
|
field_name="net_margin",
|
|
|
description="Net profit margin",
|
|
|
data_type="float",
|
|
|
unit="percentage",
|
|
|
calculation="(Net Income / Revenue) × 100",
|
|
|
source="Calculated"
|
|
|
)
|
|
|
],
|
|
|
|
|
|
"Growth Metrics": [
|
|
|
DataCatalogItem(
|
|
|
field_name="revenue_growth_yoy",
|
|
|
description="Year-over-year revenue growth rate",
|
|
|
data_type="float",
|
|
|
unit="percentage",
|
|
|
calculation="((Current Year Revenue - Previous Year Revenue) / Previous Year Revenue) × 100",
|
|
|
source="Calculated"
|
|
|
),
|
|
|
DataCatalogItem(
|
|
|
field_name="revenue_growth_qoq",
|
|
|
description="Quarter-over-quarter revenue growth rate",
|
|
|
data_type="float",
|
|
|
unit="percentage",
|
|
|
calculation="((Current Quarter Revenue - Previous Quarter Revenue) / Previous Quarter Revenue) × 100",
|
|
|
source="Calculated"
|
|
|
),
|
|
|
DataCatalogItem(
|
|
|
field_name="eps_growth_yoy",
|
|
|
description="Year-over-year EPS growth rate",
|
|
|
data_type="float",
|
|
|
unit="percentage",
|
|
|
calculation="((Current Year EPS - Previous Year EPS) / Previous Year EPS) × 100",
|
|
|
source="Calculated"
|
|
|
)
|
|
|
],
|
|
|
|
|
|
"Liquidity & Solvency": [
|
|
|
DataCatalogItem(
|
|
|
field_name="debt_to_equity",
|
|
|
description="Debt-to-Equity ratio",
|
|
|
data_type="float",
|
|
|
unit="ratio",
|
|
|
calculation="Total Debt / Total Equity",
|
|
|
source="Calculated"
|
|
|
),
|
|
|
DataCatalogItem(
|
|
|
field_name="debt_to_assets",
|
|
|
description="Debt-to-Assets ratio",
|
|
|
data_type="float",
|
|
|
unit="ratio",
|
|
|
calculation="Total Debt / Total Assets",
|
|
|
source="Calculated"
|
|
|
),
|
|
|
DataCatalogItem(
|
|
|
field_name="current_ratio",
|
|
|
description="Current assets to current liabilities ratio",
|
|
|
data_type="float",
|
|
|
unit="ratio",
|
|
|
calculation="Current Assets / Current Liabilities",
|
|
|
source="Calculated"
|
|
|
)
|
|
|
],
|
|
|
|
|
|
"Efficiency Metrics": [
|
|
|
DataCatalogItem(
|
|
|
field_name="asset_turnover",
|
|
|
description="How efficiently company uses assets to generate revenue",
|
|
|
data_type="float",
|
|
|
unit="ratio",
|
|
|
calculation="Revenue / Average Total Assets",
|
|
|
source="Calculated"
|
|
|
),
|
|
|
DataCatalogItem(
|
|
|
field_name="ocf_margin",
|
|
|
description="Operating cash flow margin",
|
|
|
data_type="float",
|
|
|
unit="percentage",
|
|
|
calculation="(Operating Cash Flow / Revenue) × 100",
|
|
|
source="Calculated"
|
|
|
),
|
|
|
DataCatalogItem(
|
|
|
field_name="fcf_margin",
|
|
|
description="Free cash flow margin",
|
|
|
data_type="float",
|
|
|
unit="percentage",
|
|
|
calculation="(Free Cash Flow / Revenue) × 100",
|
|
|
source="Calculated"
|
|
|
)
|
|
|
],
|
|
|
|
|
|
"Market Data (Future)": [
|
|
|
DataCatalogItem(
|
|
|
field_name="market_cap",
|
|
|
description="Market capitalization",
|
|
|
data_type="float",
|
|
|
unit="USD",
|
|
|
calculation="Stock Price × Shares Outstanding",
|
|
|
source="Calculated (requires price data)"
|
|
|
),
|
|
|
DataCatalogItem(
|
|
|
field_name="forward_pe",
|
|
|
description="Forward P/E ratio based on estimated earnings",
|
|
|
data_type="float",
|
|
|
unit="ratio",
|
|
|
calculation="Stock Price / Forward EPS Estimate",
|
|
|
source="External data required"
|
|
|
),
|
|
|
DataCatalogItem(
|
|
|
field_name="peg_ratio",
|
|
|
description="Price/Earnings to Growth ratio",
|
|
|
data_type="float",
|
|
|
unit="ratio",
|
|
|
calculation="P/E Ratio / Earnings Growth Rate",
|
|
|
source="External data required"
|
|
|
),
|
|
|
DataCatalogItem(
|
|
|
field_name="beta",
|
|
|
description="Stock's volatility relative to market",
|
|
|
data_type="float",
|
|
|
unit="coefficient",
|
|
|
calculation="Covariance(Stock Returns, Market Returns) / Variance(Market Returns)",
|
|
|
source="External price data required"
|
|
|
)
|
|
|
]
|
|
|
}
|
|
|
|
|
|
return catalog
|
|
|
|
|
|
@router.get(
|
|
|
"/catalog",
|
|
|
response_model=DataCatalogResponse,
|
|
|
summary="Get data catalog",
|
|
|
description="""
|
|
|
Get a comprehensive catalog of all available data fields.
|
|
|
|
|
|
This endpoint returns:
|
|
|
- All available financial metrics and their descriptions
|
|
|
- Data types and units for each field
|
|
|
- Calculation methods where applicable
|
|
|
- Data sources for each field
|
|
|
|
|
|
The catalog is organized by categories:
|
|
|
- Company Information
|
|
|
- Income Statement
|
|
|
- Balance Sheet
|
|
|
- Cash Flow Statement
|
|
|
- Valuation Ratios
|
|
|
- Profitability Metrics
|
|
|
- Growth Metrics
|
|
|
- Liquidity & Solvency
|
|
|
- Efficiency Metrics
|
|
|
- Market Data (Future)
|
|
|
"""
|
|
|
)
|
|
|
async def get_catalog(db: AsyncSession = Depends(get_db)):
|
|
|
"""Get comprehensive data catalog"""
|
|
|
|
|
|
catalog = get_data_catalog()
|
|
|
|
|
|
return DataCatalogResponse(
|
|
|
categories=catalog,
|
|
|
last_updated=datetime.utcnow()
|
|
|
) |