> For the complete documentation index, see [llms.txt](https://docs.alpha-lenz.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.alpha-lenz.com/ko/api-reference/public-api/basic-financial-api.md). # Basic Financial API Twelve Data 스타일의 간단하고 직관적인 금융 데이터 API입니다. 시계열 가격 데이터, 기업 프로필, 펀더멘털 지표를 제공합니다. **Base URL:** `/api/v1/financial-v4` **Authentication:** Optional (Trial mode supported) *** ## Time Series 종목의 과거 OHLCV (시가, 고가, 저가, 종가, 거래량) 데이터를 조회합니다. ``` GET /api/v1/financial-v4/time-series ``` ### Query Parameters | Parameter | Type | Required | Description | | ------------ | ------- | -------- | ---------------------------------------------------------- | | `symbol` | string | Yes | Stock ticker symbol (e.g., "005930") | | `interval` | string | No | Time interval: `1day`, `1week`, `1month` (default: `1day`) | | `outputsize` | integer | No | Number of data points (1-5000, default: 30) | | `start_date` | string | No | Start date filter (YYYY-MM-DD) | | `end_date` | string | No | End date filter (YYYY-MM-DD) | ### Example Request ```bash curl -X GET "https://api.alpha-lenz.com/api/v1/financial-v4/time-series?symbol=005930&interval=1day&outputsize=100" ``` ### Response ```json { "meta": { "symbol": "005930", "name": "삼성전자", "exchange": "KRX", "currency": "KRW", "interval": "1day", "data_points": 100 }, "values": [ { "datetime": "2024-01-01T00:00:00", "open": 71000.0, "high": 72000.0, "low": 70500.0, "close": 71500.0, "volume": 15000000 }, { "datetime": "2024-01-02T00:00:00", "open": 71500.0, "high": 72500.0, "low": 71000.0, "close": 72000.0, "volume": 18000000 } ], "status": "ok" } ``` ### Response Fields **meta:** * `symbol` - Stock ticker symbol * `name` - Company name * `exchange` - Exchange code (e.g., KRX) * `currency` - Trading currency (e.g., KRW) * `interval` - Time interval of the data * `data_points` - Number of data points returned **values (array):** * `datetime` - ISO 8601 timestamp * `open` - Opening price * `high` - Highest price * `low` - Lowest price * `close` - Closing price * `volume` - Trading volume *** ## Profile 기업의 상세 정보, 연락처, 주소, 식별자를 조회합니다. ``` GET /api/v1/financial-v4/profile ``` ### Query Parameters | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------- | | `symbol` | string | Yes | Stock ticker symbol | ### Example Request ```bash curl -X GET "https://api.alpha-lenz.com/api/v1/financial-v4/profile?symbol=005930" ``` ### Response ```json { "symbol": "005930", "name": "삼성전자", "exchange": "KRX", "mic_code": "XKRX", "sector": "Technology", "industry": "Electronics", "currency": "KRW", "figi_code": "BBG000BCL938", "isin": "KR7005930003", "cusip": null, "description": "삼성전자는 반도체, 디스플레이, IT & 모바일 통신 사업을 영위하는 글로벌 기업입니다.", "ceo": "한종희", "employees": 270372, "website": "https://www.samsung.com", "address": "경기도 수원시 영통구 삼성로 129", "city": "수원시", "state": "경기도", "zip_code": "16677", "country": "대한민국", "phone": "+82-31-200-1114", "shares_outstanding": 5969782550, "stock_type": "Common Stock", "latest_price": 71500.0, "market_cap": 426889574325000, "status": "ok" } ``` ### Response Fields **Basic Information:** * `symbol` - Stock ticker * `name` - Company name * `exchange` - Exchange code * `mic_code` - Market Identifier Code * `sector` - Business sector * `industry` - Industry classification **Identifiers:** * `currency` - Trading currency * `figi_code` - Financial Instrument Global Identifier * `isin` - International Securities Identification Number * `cusip` - CUSIP number (US securities) **Company Details:** * `description` - Business description * `ceo` - Chief Executive Officer * `employees` - Number of employees * `website` - Company website **Address:** * `address` - Street address * `city` - City * `state` - State/Province * `zip_code` - Postal code * `country` - Country * `phone` - Contact phone **Share Information:** * `shares_outstanding` - Total shares * `stock_type` - Type of stock **Market Data:** * `latest_price` - Latest stock price * `market_cap` - Market capitalization *** ## Fundamentals 재무 비율, 밸류에이션 지표, 성장률 데이터를 조회합니다. ``` GET /api/v1/financial-v4/fundamentals ``` ### Query Parameters | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------- | | `symbol` | string | Yes | Stock ticker symbol | ### Example Request ```bash curl -X GET "https://api.alpha-lenz.com/api/v1/financial-v4/fundamentals?symbol=005930" ``` ### Response ```json { "symbol": "005930", "name": "삼성전자", "exchange": "KRX", "currency": "KRW", "valuation": { "pe_ratio": 15.23, "pb_ratio": 1.45, "ps_ratio": 1.12, "ev_ebitda": 8.45, "pfcf_ratio": 12.34 }, "growth": { "sales_growth_1y": 8.5, "sales_growth_3y_cagr": 6.2, "sales_growth_5y_cagr": 5.8, "operating_income_growth_1y": 12.3, "operating_income_growth_3y_cagr": 9.1, "operating_income_growth_5y_cagr": 7.5 }, "market_data": { "market_cap": 426889574325000, "latest_price": 71500.0, "latest_volume": 15000000, "dividend_yield": 2.5, "shares_outstanding": 5969782550 }, "status": "ok" } ``` ### Response Fields **valuation (Valuation Ratios):** * `pe_ratio` - Price-to-Earnings ratio (PER) * `pb_ratio` - Price-to-Book ratio (PBR) * `ps_ratio` - Price-to-Sales ratio (PSR) * `ev_ebitda` - Enterprise Value / EBITDA * `pfcf_ratio` - Price to Free Cash Flow ratio **growth (Growth Metrics):** * `sales_growth_1y` - 1-year sales growth (%) * `sales_growth_3y_cagr` - 3-year sales CAGR (%) * `sales_growth_5y_cagr` - 5-year sales CAGR (%) * `operating_income_growth_1y` - 1-year operating income growth (%) * `operating_income_growth_3y_cagr` - 3-year operating income CAGR (%) * `operating_income_growth_5y_cagr` - 5-year operating income CAGR (%) **market\_data (Market Data):** * `market_cap` - Market capitalization * `latest_price` - Latest stock price * `latest_volume` - Latest trading volume * `dividend_yield` - Dividend yield (%) * `shares_outstanding` - Total shares outstanding *** ## Error Responses All endpoints return standard error responses: ### 404 Not Found ```json { "detail": "Symbol '999999' not found" } ``` ### 422 Validation Error ```json { "detail": [ { "loc": ["query", "outputsize"], "msg": "ensure this value is less than or equal to 5000", "type": "value_error.number.not_le" } ] } ``` ### 500 Internal Server Error ```json { "detail": "Internal server error occurred" } ``` *** ## Use Cases ### 1. Building a Stock Price Chart Get historical price data for visualization: ```bash # Get 90 days of daily prices curl "https://api.alpha-lenz.com/api/v1/financial-v4/time-series?symbol=005930&interval=1day&outputsize=90" # Get 52 weeks of weekly prices curl "https://api.alpha-lenz.com/api/v1/financial-v4/time-series?symbol=005930&interval=1week&outputsize=52" ``` ### 2. Company Research Dashboard Combine profile and fundamentals data: ```bash # Get company information curl "https://api.alpha-lenz.com/api/v1/financial-v4/profile?symbol=005930" # Get financial metrics curl "https://api.alpha-lenz.com/api/v1/financial-v4/fundamentals?symbol=005930" ``` ### 3. Multi-Timeframe Analysis Compare different time periods: ```bash # Daily data (short-term) curl "https://api.alpha-lenz.com/api/v1/financial-v4/time-series?symbol=005930&interval=1day&outputsize=30" # Weekly data (medium-term) curl "https://api.alpha-lenz.com/api/v1/financial-v4/time-series?symbol=005930&interval=1week&outputsize=52" # Monthly data (long-term) curl "https://api.alpha-lenz.com/api/v1/financial-v4/time-series?symbol=005930&interval=1month&outputsize=60" ``` ### 4. Historical Period Analysis Get data for a specific date range: ```bash # Get Q4 2023 daily prices curl "https://api.alpha-lenz.com/api/v1/financial-v4/time-series?symbol=005930&interval=1day&start_date=2023-10-01&end_date=2023-12-31" ``` *** ## Rate Limits Currently, these endpoints support **trial mode** without rate limits. For production use: * Standard tier: 100 requests/minute * Premium tier: 1000 requests/minute * Enterprise tier: Custom limits Contact support for API key and tier upgrade. *** ## Comparison with Twelve Data | Feature | Twelve Data | Basic Financial API | Notes | | -------------------- | ----------- | ------------------- | ----------------------- | | Time Series | ✅ | ✅ | Similar structure | | Company Profile | ✅ | ✅ | Full company info | | Fundamentals | ✅ | ✅ | Valuation & growth | | Real-time Quote | ✅ | ⏳ | Coming soon | | Technical Indicators | ✅ | ❌ | Use `/stock-prices` API | | Logo | ✅ | ❌ | Not implemented | | WebSocket | ✅ | ❌ | Not implemented | *** ## Related APIs * [**Stock API**](/ko/api-reference/public-api/stock.md) - Advanced stock price data with technical indicators * [**Financial API**](/ko/api-reference/public-api/financial.md) - Detailed financial statements and company data * [**News API**](/ko/api-reference/public-api/news.md) - Company news and market updates *** ## Support For questions or issues: * Check [API Documentation](https://github.com/TeamZikto/argo-lng-mono/blob/main/docs/README.md) * Contact support team * Visit GitHub repository --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.alpha-lenz.com/ko/api-reference/public-api/basic-financial-api.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.