Upload 10 files

API_ENHANCEMENTS.md

@@ -0,0 +1,260 @@
+# API Enhancements Summary
+
+## Overview
+
+The MCP Server has been enhanced to include all important methods from `FinancialAnalyzer`, providing both basic and advanced financial data analysis capabilities.
+
+## Total API Endpoints: 9
+
+### Basic Endpoints (6) - Using `EdgarDataClient`
+
+1. **POST /api/search_company**
+   - Search company by name
+   - Returns: CIK, name, ticker
+
+2. **POST /api/get_company_info**
+   - Get detailed company information
+   - Returns: Full company details with SIC
+
+3. **POST /api/get_company_filings**
+   - Get company SEC filings
+   - Supports: 10-K, 10-Q, 20-F, etc.
+
+4. **POST /api/get_company_facts**
+   - Get complete XBRL financial facts
+   - Returns: Raw financial data
+
+5. **POST /api/get_financial_data**
+   - Get financial data for specific period
+   - Supports: Annual (YYYY) and Quarterly (YYYYQX)
+
+6. **GET /health**
+   - Health check endpoint
+   - Returns: Server status
+
+### Advanced Endpoints (3) - Using `FinancialAnalyzer` ⭐
+
+#### 7. POST /api/advanced_search
+**Purpose**: Intelligent company search supporting both name and CIK
+
+**From**: `FinancialAnalyzer.search_company()`
+
+**Request**:
+```json
+{
+  "company_input": "Apple"  // or "0000320193"
+}
+```
+
+**Features**:
+- Auto-detects input type (name vs CIK)
+- Returns complete company information
+- More intelligent than basic search
+
+**Use Case**: When you don't know if user input is name or CIK
+
+---
+
+#### 8. POST /api/extract_financial_metrics
+**Purpose**: Extract multi-year financial metrics (annual + quarterly)
+
+**From**: `FinancialAnalyzer.extract_financial_metrics()`
+
+**Request**:
+```json
+{
+  "cik": "0001045810",
+  "years": 3
+}
+```
+
+**Response**:
+```json
+{
+  "metrics": [
+    {
+      "period": "2024",
+      "total_revenue": 60922000000,
+      "net_income": 29760000000,
+      "earnings_per_share": 12.04,
+      ...
+    },
+    {
+      "period": "2024Q4",
+      ...
+    },
+    {
+      "period": "2024Q3",
+      ...
+    }
+  ],
+  "count": 15
+}
+```
+
+**Features**:
+- Returns both annual and quarterly data
+- Automatically formats data
+- Sorted by period (newest first)
+- Configurable years (1-10)
+
+**Use Cases**:
+- Historical trend analysis
+- Multi-period comparison
+- Financial modeling
+- Data visualization
+
+---
+
+#### 9. POST /api/get_latest_financial_data
+**Purpose**: Get the most recent annual financial data
+
+**From**: `FinancialAnalyzer.get_latest_financial_data()`
+
+**Request**:
+```json
+{
+  "cik": "0001045810"
+}
+```
+
+**Response**:
+```json
+{
+  "period": "2024",
+  "total_revenue": 60922000000,
+  "net_income": 29760000000,
+  "earnings_per_share": 12.04,
+  "operating_expenses": 11822000000,
+  "operating_cash_flow": 28091000000,
+  "source_url": "https://www.sec.gov/...",
+  "source_form": "10-K"
+}
+```
+
+**Features**:
+- Automatically finds latest fiscal year
+- No need to know the year
+- Returns most recent 10-K or 20-F data
+
+**Use Cases**:
+- Quick company snapshot
+- Current financial position
+- Latest performance metrics
+
+---
+
+## Key Benefits
+
+### 1. **Flexibility**
+- Basic endpoints for precise queries
+- Advanced endpoints for intelligent analysis
+
+### 2. **Efficiency**
+- `extract_financial_metrics` - Get multiple years in one call
+- `get_latest_financial_data` - No need to determine fiscal year
+- `advanced_search` - Flexible input handling
+
+### 3. **Complete Coverage**
+All important `FinancialAnalyzer` methods are now exposed:
+- ✅ `search_company()` → `/api/advanced_search`
+- ✅ `extract_financial_metrics()` → `/api/extract_financial_metrics`
+- ✅ `get_latest_financial_data()` → `/api/get_latest_financial_data`
+
+### 4. **Data Quality**
+- Automatic data formatting
+- Consistent response structure
+- Comprehensive error handling
+
+## Comparison: Basic vs Advanced
+
+| Feature | Basic Endpoint | Advanced Endpoint |
+|---------|---------------|-------------------|
+| Company Search | `/api/search_company` | `/api/advanced_search` |
+| Input Type | Name only | Name or CIK |
+| Return Data | Basic (CIK, name, ticker) | Complete (includes SIC) |
+| | | |
+| Financial Data | `/api/get_financial_data` | `/api/extract_financial_metrics` |
+| Period | Single period | Multiple years |
+| Data Type | Annual OR quarterly | Annual AND quarterly |
+| Request Count | 1 per period | 1 for all periods |
+| | | |
+| Latest Data | `/api/get_financial_data` | `/api/get_latest_financial_data` |
+| Year Required | Yes (must specify) | No (auto-detects) |
+| Convenience | Manual | Automatic |
+
+## Usage Examples
+
+### Example 1: Quick Company Analysis
+
+```python
+import requests
+
+BASE_URL = "https://YOUR_SPACE.hf.space"
+
+# Step 1: Advanced search (works with name or CIK)
+response = requests.post(
+    f"{BASE_URL}/api/advanced_search",
+    json={"company_input": "NVIDIA"}
+)
+company = response.json()
+cik = company['cik']
+
+# Step 2: Get latest data (no year needed!)
+response = requests.post(
+    f"{BASE_URL}/api/get_latest_financial_data",
+    json={"cik": cik}
+)
+latest = response.json()
+print(f"Latest FY{latest['period']} Revenue: ${latest['total_revenue']:,.0f}")
+```
+
+### Example 2: Multi-Year Trend Analysis
+
+```python
+# Get 5 years of data in one call
+response = requests.post(
+    f"{BASE_URL}/api/extract_financial_metrics",
+    json={"cik": cik, "years": 5}
+)
+data = response.json()
+
+# Analyze trends
+import pandas as pd
+df = pd.DataFrame(data['metrics'])
+annual_data = df[~df['period'].str.contains('Q')]  # Filter annual only
+print(annual_data[['period', 'total_revenue', 'net_income']])
+```
+
+### Example 3: Flexible Search
+
+```python
+# Works with either input type
+def search_company(input_str):
+    response = requests.post(
+        f"{BASE_URL}/api/advanced_search",
+        json={"company_input": input_str}
+    )
+    return response.json()
+
+# Both work!
+result1 = search_company("Apple")         # By name
+result2 = search_company("0000320193")    # By CIK
+```
+
+## Documentation
+
+- **Complete API Examples**: See `mcp_client_examples.json`
+- **Interactive Testing**: Visit `/docs` (Swagger UI)
+- **Detailed Usage**: See `API_USAGE.md`
+
+## Summary
+
+The MCP Server now provides **9 comprehensive API endpoints** covering:
+- ✅ Basic data retrieval (EdgarDataClient)
+- ✅ Advanced analysis (FinancialAnalyzer)
+- ✅ Flexible search options
+- ✅ Multi-year data extraction
+- ✅ Automatic latest data retrieval
+
+All important functionality from both `edgar_client.py` and `financial_analyzer.py` is now accessible via RESTful APIs! 🎉

README.md

@@ -42,6 +42,7 @@ Once deployed, visit `/docs` for interactive Swagger UI documentation or `/redoc
 
 ## API Endpoints
 
+### Basic Endpoints
 - `POST /api/search_company` - Search company by name
 - `POST /api/get_company_info` - Get company information
 - `POST /api/get_company_filings` - Get company filings
@@ -49,6 +50,11 @@ Once deployed, visit `/docs` for interactive Swagger UI documentation or `/redoc
 - `POST /api/get_financial_data` - Get financial data for period
 - `GET /health` - Health check
 
+### Advanced Endpoints (FinancialAnalyzer)
+- `POST /api/advanced_search` - Advanced search (supports name or CIK)
+- `POST /api/extract_financial_metrics` - Extract multi-year metrics
+- `POST /api/get_latest_financial_data` - Get latest annual data
+
 ## Usage Example
 
 ```python

financial_analyzer.py

@@ -0,0 +1,248 @@
+"""Financial Data Analysis Module"""
+
+from edgar_client import EdgarDataClient
+from datetime import datetime
+import json
+
+
+class FinancialAnalyzer:
+    def __init__(self, user_agent="Juntao Peng Financial Report Metrics App (jtyxabc@gmail.com)"):
+        """
+        初始化财务分析器
+        
+        Args:
+            user_agent (str): 用户代理字符串，用于识别请求来源
+        """
+        self.edgar_client = EdgarDataClient(user_agent)
+        
+    def search_company(self, company_input):
+        """
+        搜索公司信息（通过名称或CIK）
+        
+        Args:
+            company_input (str): 公司名称或CIK
+            
+        Returns:
+            dict: 公司信息
+        """
+        # 如果输入是数字，假设它是CIK
+        if company_input.isdigit() and len(company_input) >= 8:
+            # 获取公司信息
+            company_info = self.edgar_client.get_company_info(company_input)
+            if company_info:
+                return company_info
+            else:
+                return {"error": "未找到指定CIK的公司"}
+        else:
+            # 通过名称搜索公司
+            company = self.edgar_client.search_company_by_name(company_input)
+            if company:
+                # 获取详细信息
+                company_info = self.edgar_client.get_company_info(company['cik'])
+                if company_info:
+                    return company_info
+                else:
+                    # 如果无法获取详细信息，返回基本信息
+                    return {
+                        "cik": company['cik'],
+                        "name": company['name'],
+                        "tickers": [company['ticker']] if company['ticker'] else []
+                    }
+            else:
+                return {"error": "未找到匹配的公司"}
+    
+    def get_company_filings_list(self, cik, form_types=['10-K', '10-Q']):
+        """
+        获取公司财报列表
+        
+        Args:
+            cik (str): 公司CIK
+            form_types (list): 财报类型列表
+            
+        Returns:
+            list: 财报列表
+        """
+        filings = self.edgar_client.get_company_filings(cik, form_types)
+        return filings
+    
+    def extract_financial_metrics(self, cik, years=3):
+        """
+        提取指定年数的财务指标
+        
+        Args:
+            cik (str): 公司CIK
+            years (int): 要提取的年数，默认为3年
+            
+        Returns:
+            list: 财务数据列表
+        """
+        # 直接从company facts中获取所有可用的财年数据
+        # 这样可以避免filing date和fiscal year不匹配的问题
+        financial_data = []
+        
+        # 获取company facts以确定可用的财年
+        facts = self.edgar_client.get_company_facts(cik)
+        if not facts:
+            return []
+        
+        # 从facts中提取所有可用的财年
+        available_years = set()
+        
+        # 检查US-GAAP和IFRS数据源
+        for data_source in ["us-gaap", "ifrs-full"]:
+            if data_source in facts.get("facts", {}):
+                source_data = facts["facts"][data_source]
+                
+                # 查找Revenue标签以确定可用年份
+                revenue_tags = ["Revenues", "RevenueFromContractWithCustomerExcludingAssessedTax", 
+                               "Revenue", "RevenueFromContractWithCustomer"]
+                
+                for tag in revenue_tags:
+                    if tag in source_data:
+                        units = source_data[tag].get("units", {})
+                        if "USD" in units:
+                            for entry in units["USD"]:
+                                # 只考虑年度报告（10-K或20-F）
+                                if entry.get("form") in ["10-K", "20-F"]:
+                                    # 优先使用fy字段（财政年度）
+                                    fy = entry.get("fy", 0)
+                                    if fy > 0:
+                                        available_years.add(fy)
+                                    # 如果没有fy字段，从end date提取年份作为备选
+                                    # 注意：对于财年不等于日历年的公司，这可能不准确
+                                    elif not fy:
+                                        end_date = entry.get("end", "")
+                                        if end_date and len(end_date) >= 4:
+                                            year = int(end_date[:4])
+                                            available_years.add(year)
+                        break
+                if available_years:
+                    break
+        
+        if not available_years:
+            # 如果无法从facts获取，回退到使用filing date
+            filings_10k = self.edgar_client.get_company_filings(cik, ['10-K'])
+            filings_20f = self.edgar_client.get_company_filings(cik, ['20-F'])
+            filings = filings_10k + filings_20f
+            
+            if not filings:
+                return []
+            
+            # 使用filing date作为参考
+            latest_filing_year = None
+            for filing in filings:
+                if 'filing_date' in filing and filing['filing_date']:
+                    try:
+                        filing_year = int(filing['filing_date'][:4])
+                        if latest_filing_year is None or filing_year > latest_filing_year:
+                            latest_filing_year = filing_year
+                    except ValueError:
+                        continue
+            
+            if latest_filing_year is None:
+                return []
+            
+            # 生成年份列表
+            for i in range(years * 2):  # 扩大范围以捕获更多数据
+                available_years.add(latest_filing_year - i)
+        
+        # 按年份降序排列
+        sorted_years = sorted(available_years, reverse=True)
+        
+        # 生成期间列表（年度和季度）
+        periods = []
+        for year in sorted_years[:years]:
+            # 添加年度数据
+            periods.append(str(year))
+            # 添加季度数据，按Q4、Q3、Q2、Q1顺序
+            for quarter in range(4, 0, -1):
+                periods.append(f"{year}Q{quarter}")
+        
+        # 获取每个期间的财务数据
+        for period in periods:
+            data = self.edgar_client.get_financial_data_for_period(cik, period)
+            # 即使没有完整数据也添加，避免N/A情况
+            if data:  # 只要period字段存在就添加
+                financial_data.append(data)
+        
+        return financial_data
+    
+    def get_latest_financial_data(self, cik):
+        """
+        获取最新财务数据
+        
+        Args:
+            cik (str): 公司CIK
+            
+        Returns:
+            dict: 最新财务数据
+        """
+        # 获取最近的财报年份（支持10-K和20-F）
+        filings_10k = self.edgar_client.get_company_filings(cik, ['10-K'])
+        filings_20f = self.edgar_client.get_company_filings(cik, ['20-F'])
+        filings = filings_10k + filings_20f
+        
+        if not filings:
+            return {}
+        
+        # 获取最新的财报年份
+        latest_filing_year = None
+        for filing in filings:
+            if 'filing_date' in filing and filing['filing_date']:
+                try:
+                    filing_year = int(filing['filing_date'][:4])
+                    if latest_filing_year is None or filing_year > latest_filing_year:
+                        latest_filing_year = filing_year
+                except ValueError:
+                    continue
+        
+        if latest_filing_year is None:
+            return {}
+        
+        # 获取最新年份的财务数据
+        return self.edgar_client.get_financial_data_for_period(cik, str(latest_filing_year))
+    
+    def format_financial_data(self, financial_data):
+        """
+        格式化财务数据以便显示
+        
+        Args:
+            financial_data (dict or list): 财务数据
+            
+        Returns:
+            dict or list: 格式化后的财务数据
+        """
+        if isinstance(financial_data, list):
+            formatted_data = []
+            for data in financial_data:
+                formatted_data.append(self._format_single_financial_data(data))
+            return formatted_data
+        else:
+            return self._format_single_financial_data(financial_data)
+    
+    def _format_single_financial_data(self, data):
+        """
+        格式化单个财务数据条目
+        
+        Args:
+            data (dict): 财务数据
+            
+        Returns:
+            dict: 格式化后的财务数据
+        """
+        formatted = data.copy()
+        
+        # 确保所有关键字段都存在，即使为None
+        key_fields = ['total_revenue', 'net_income', 'earnings_per_share', 'operating_expenses', 'operating_cash_flow', 'source_url', 'source_form']
+        for key in key_fields:
+            if key not in formatted:
+                formatted[key] = None
+        
+        # 不再进行单位转换，保持原始数值
+        # 格式化EPS，保留两位小数
+        if 'earnings_per_share' in formatted and isinstance(formatted['earnings_per_share'], (int, float)):
+            formatted['earnings_per_share'] = round(formatted['earnings_per_share'], 2)
+            
+        return formatted
+
+

mcp_client_examples.json

@@ -331,6 +331,135 @@
         "Use for monitoring and health checks",
         "Always returns 200 if server is running"
       ]
+    },
+
+    "8_advanced_search": {
+      "name": "Advanced Company Search",
+      "endpoint": "/api/advanced_search",
+      "method": "POST",
+      "description": "Advanced search supporting both company name and CIK (uses FinancialAnalyzer.search_company)",
+      
+      "request_by_name": {
+        "company_input": "Apple"
+      },
+      
+      "request_by_cik": {
+        "company_input": "0000320193"
+      },
+      
+      "response_success": {
+        "cik": "0000320193",
+        "name": "Apple Inc.",
+        "tickers": ["AAPL"],
+        "sic": "3571",
+        "sic_description": "Electronic Computers",
+        "error": null
+      },
+      
+      "curl_example": "curl -X POST 'https://YOUR_SPACE.hf.space/api/advanced_search' -H 'Content-Type: application/json' -d '{\"company_input\": \"Apple\"}'"  ,
+      
+      "python_example": "import requests\n\n# Search by name\nresponse = requests.post(\n    'https://YOUR_SPACE.hf.space/api/advanced_search',\n    json={'company_input': 'Apple'}\n)\nprint(response.json())\n\n# Search by CIK\nresponse = requests.post(\n    'https://YOUR_SPACE.hf.space/api/advanced_search',\n    json={'company_input': '0000320193'}\n)\nprint(response.json())",
+      
+      "javascript_example": "// Flexible search - works with both name and CIK\nfetch('https://YOUR_SPACE.hf.space/api/advanced_search', {\n  method: 'POST',\n  headers: {'Content-Type': 'application/json'},\n  body: JSON.stringify({company_input: 'Apple'})\n}).then(r => r.json()).then(console.log)",
+      
+      "notes": [
+        "Automatically detects if input is CIK (numeric, 8+ digits) or company name",
+        "Returns full company information including SIC",
+        "More intelligent than basic search_company endpoint"
+      ]
+    },
+
+    "9_extract_financial_metrics": {
+      "name": "Extract Multi-Year Financial Metrics",
+      "endpoint": "/api/extract_financial_metrics",
+      "method": "POST",
+      "description": "Extract financial metrics for multiple years (both annual and quarterly data)",
+      
+      "request_example": {
+        "cik": "0001045810",
+        "years": 3
+      },
+      
+      "response_success": {
+        "metrics": [
+          {
+            "period": "2024",
+            "total_revenue": 60922000000,
+            "net_income": 29760000000,
+            "earnings_per_share": 12.04,
+            "operating_expenses": 11822000000,
+            "operating_cash_flow": 28091000000,
+            "source_form": "10-K",
+            "data_source": "us-gaap"
+          },
+          {
+            "period": "2024Q4",
+            "total_revenue": 35082000000,
+            "net_income": 19309000000,
+            "earnings_per_share": 7.81,
+            "source_form": "10-Q"
+          },
+          {
+            "period": "2024Q3",
+            "total_revenue": 30040000000,
+            "net_income": 16599000000,
+            "earnings_per_share": 6.70,
+            "source_form": "10-Q"
+          }
+        ],
+        "count": 3,
+        "error": null
+      },
+      
+      "curl_example": "curl -X POST 'https://YOUR_SPACE.hf.space/api/extract_financial_metrics' -H 'Content-Type: application/json' -d '{\"cik\": \"0001045810\", \"years\": 3}'",
+      
+      "python_example": "import requests\nimport pandas as pd\n\nresponse = requests.post(\n    'https://YOUR_SPACE.hf.space/api/extract_financial_metrics',\n    json={'cik': '0001045810', 'years': 3}\n)\ndata = response.json()\n\n# Convert to DataFrame for easy analysis\ndf = pd.DataFrame(data['metrics'])\nprint(f\"Retrieved {data['count']} periods\")\nprint(df[['period', 'total_revenue', 'net_income', 'earnings_per_share']])",
+      
+      "javascript_example": "fetch('https://YOUR_SPACE.hf.space/api/extract_financial_metrics', {\n  method: 'POST',\n  headers: {'Content-Type': 'application/json'},\n  body: JSON.stringify({cik: '0001045810', years: 3})\n}).then(r => r.json()).then(data => {\n  console.log(`Found ${data.count} periods`);\n  data.metrics.forEach(m => {\n    console.log(`${m.period}: Revenue $${(m.total_revenue/1e9).toFixed(2)}B`);\n  });\n})",
+      
+      "notes": [
+        "Returns both annual (e.g., '2024') and quarterly (e.g., '2024Q3') data",
+        "Data is automatically formatted and sorted by period",
+        "Years parameter: min=1, max=10, default=3",
+        "Very useful for trend analysis and historical comparison"
+      ]
+    },
+
+    "10_get_latest_financial_data": {
+      "name": "Get Latest Financial Data",
+      "endpoint": "/api/get_latest_financial_data",
+      "method": "POST",
+      "description": "Get the most recent annual financial data for a company",
+      
+      "request_example": {
+        "cik": "0001045810"
+      },
+      
+      "response_success": {
+        "period": "2024",
+        "total_revenue": 60922000000,
+        "net_income": 29760000000,
+        "earnings_per_share": 12.04,
+        "operating_expenses": 11822000000,
+        "operating_cash_flow": 28091000000,
+        "source_url": "https://www.sec.gov/Archives/edgar/data/1045810/000104581024000029",
+        "source_form": "10-K",
+        "data_source": "us-gaap",
+        "error": null
+      },
+      
+      "curl_example": "curl -X POST 'https://YOUR_SPACE.hf.space/api/get_latest_financial_data' -H 'Content-Type: application/json' -d '{\"cik\": \"0001045810\"}'  ",
+      
+      "python_example": "import requests\n\nresponse = requests.post(\n    'https://YOUR_SPACE.hf.space/api/get_latest_financial_data',\n    json={'cik': '0001045810'}\n)\ndata = response.json()\n\nif not data.get('error'):\n    print(f\"Latest Data: FY{data['period']}\")\n    print(f\"Revenue: ${data['total_revenue']:,.0f}\")\n    print(f\"Net Income: ${data['net_income']:,.0f}\")\n    print(f\"EPS: ${data['earnings_per_share']:.2f}\")\n    print(f\"Source: {data['source_form']}\")\nelse:\n    print(f\"Error: {data['error']}\")",
+      
+      "javascript_example": "fetch('https://YOUR_SPACE.hf.space/api/get_latest_financial_data', {\n  method: 'POST',\n  headers: {'Content-Type': 'application/json'},\n  body: JSON.stringify({cik: '0001045810'})\n}).then(r => r.json()).then(data => {\n  if (!data.error) {\n    console.log(`Latest FY${data.period}`);\n    console.log(`Revenue: $${(data.total_revenue/1e9).toFixed(2)}B`);\n    console.log(`Net Income: $${(data.net_income/1e9).toFixed(2)}B`);\n  }\n})",
+      
+      "notes": [
+        "Automatically finds and returns the most recent annual report data",
+        "Saves you from having to manually determine the latest year",
+        "Returns data from most recent 10-K or 20-F filing",
+        "Ideal for getting current snapshot without knowing fiscal year"
+      ]
     }
   },
 

mcp_server.py

@@ -8,6 +8,7 @@ from fastapi.middleware.cors import CORSMiddleware
 from pydantic import BaseModel, Field
 from typing import Optional, List, Dict, Any
 from edgar_client import EdgarDataClient
+from financial_analyzer import FinancialAnalyzer
 import uvicorn
 
 # Initialize FastAPI app
@@ -31,6 +32,11 @@ edgar_client = EdgarDataClient(
     user_agent="Juntao Peng Financial Report Metrics App (jtyxabc@gmail.com)"
 )
 
+# Initialize Financial Analyzer
+financial_analyzer = FinancialAnalyzer(
+    user_agent="Juntao Peng Financial Report Metrics App (jtyxabc@gmail.com)"
+)
+
 
 # Request/Response Models
 class UserAgentRequest(BaseModel):
@@ -68,6 +74,19 @@ class FinancialDataRequest(BaseModel):
     )
 
 
+class AdvancedSearchRequest(BaseModel):
+    company_input: str = Field(..., description="Company name or CIK code")
+
+
+class ExtractMetricsRequest(BaseModel):
+    cik: str = Field(..., description="Company CIK code")
+    years: int = Field(default=3, description="Number of years to extract", ge=1, le=10)
+
+
+class LatestDataRequest(BaseModel):
+    cik: str = Field(..., description="Company CIK code")
+
+
 class CompanySearchResponse(BaseModel):
     cik: Optional[str] = None
     name: Optional[str] = None
@@ -115,6 +134,12 @@ class FinancialDataResponse(BaseModel):
     error: Optional[str] = None
 
 
+class MetricsListResponse(BaseModel):
+    metrics: List[Dict[str, Any]] = []
+    count: int = 0
+    error: Optional[str] = None
+
+
 # API Endpoints
 @app.get("/")
 async def root():
@@ -126,10 +151,13 @@ async def root():
         "endpoints": {
             "health": "/health",
             "search_company": "/api/search_company",
+            "advanced_search": "/api/advanced_search",
             "get_company_info": "/api/get_company_info",
             "get_company_filings": "/api/get_company_filings",
             "get_company_facts": "/api/get_company_facts",
-            "get_financial_data": "/api/get_financial_data"
+            "get_financial_data": "/api/get_financial_data",
+            "extract_financial_metrics": "/api/extract_financial_metrics",
+            "get_latest_financial_data": "/api/get_latest_financial_data"
         },
         "user_agent": "Juntao Peng (jtyxabc@gmail.com)"
     }
@@ -302,6 +330,111 @@ async def get_financial_data_for_period(request: FinancialDataRequest):
         raise HTTPException(status_code=500, detail=str(e))
 
 
+@app.post("/api/advanced_search", response_model=CompanyInfoResponse)
+async def advanced_search_company(request: AdvancedSearchRequest):
+    """
+    Advanced company search (supports both company name and CIK)
+    Uses FinancialAnalyzer.search_company() method
+    
+    Args:
+        company_input (str): Company name or CIK code
+        
+    Returns:
+        dict: Company information
+    """
+    try:
+        result = financial_analyzer.search_company(request.company_input)
+        
+        if result.get("error"):
+            return CompanyInfoResponse(error=result["error"])
+        
+        return CompanyInfoResponse(
+            cik=result.get("cik"),
+            name=result.get("name"),
+            tickers=result.get("tickers"),
+            sic=result.get("sic"),
+            sic_description=result.get("sic_description")
+        )
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.post("/api/extract_financial_metrics", response_model=MetricsListResponse)
+async def extract_financial_metrics(request: ExtractMetricsRequest):
+    """
+    Extract financial metrics for multiple years (annual and quarterly)
+    Uses FinancialAnalyzer.extract_financial_metrics() method
+    
+    Args:
+        cik (str): Company CIK code
+        years (int): Number of years to extract (default: 3, max: 10)
+        
+    Returns:
+        dict: List of financial metrics for multiple periods
+    """
+    try:
+        metrics = financial_analyzer.extract_financial_metrics(request.cik, request.years)
+        
+        if not metrics:
+            return MetricsListResponse(
+                metrics=[],
+                count=0,
+                error=f"No financial metrics found for CIK: {request.cik}"
+            )
+        
+        # Format the metrics
+        formatted_metrics = financial_analyzer.format_financial_data(metrics)
+        
+        return MetricsListResponse(
+            metrics=formatted_metrics,
+            count=len(formatted_metrics)
+        )
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.post("/api/get_latest_financial_data", response_model=FinancialDataResponse)
+async def get_latest_financial_data(request: LatestDataRequest):
+    """
+    Get the latest financial data for a company
+    Uses FinancialAnalyzer.get_latest_financial_data() method
+    
+    Args:
+        cik (str): Company CIK code
+        
+    Returns:
+        dict: Latest financial data
+    """
+    try:
+        result = financial_analyzer.get_latest_financial_data(request.cik)
+        
+        if not result or "period" not in result:
+            return FinancialDataResponse(
+                error=f"No latest financial data found for CIK: {request.cik}"
+            )
+        
+        # Collect additional details
+        additional_details = {}
+        for key, value in result.items():
+            if key.endswith("_details"):
+                additional_details[key] = value
+        
+        return FinancialDataResponse(
+            period=result.get("period"),
+            total_revenue=result.get("total_revenue"),
+            net_income=result.get("net_income"),
+            earnings_per_share=result.get("earnings_per_share"),
+            operating_expenses=result.get("operating_expenses"),
+            operating_cash_flow=result.get("operating_cash_flow"),
+            source_url=result.get("source_url"),
+            source_form=result.get("source_form"),
+            data_source=result.get("data_source"),
+            additional_details=additional_details if additional_details else None
+        )
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
 if __name__ == "__main__":
     # Run the server
     uvicorn.run(