> 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/en/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**](/en/api-reference/public-api/stock.md) - Advanced stock price data with technical indicators
* [**Financial API**](/en/api-reference/public-api/financial.md) - Detailed financial statements and company data
* [**News API**](/en/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