# API 가이드
krx-rs가 제공하는 모든 API 엔드포인트와 사용법을 설명합니다.
## API 구조
krx-rs는 KRX Open API를 7개의 주요 카테고리로 구성합니다:
1. **Stock** - 주식 관련 API
2. **Index** - 지수 관련 API
3. **Bond** - 채권 관련 API
4. **ETP** - ETF, ETN, ELW 관련 API
5. **Derivative** - 파생상품 관련 API
6. **General** - 일반상품 (유가, 금, 배출권) API
7. **ESG** - ESG 관련 API
## Stock API
### KOSPI 일별 시세
```rust
let data = client.stock()
.kospi_daily()
.date("20240105")
.fetch()
.await?;
```
### KOSDAQ 일별 시세
```rust
let data = client.stock()
.kosdaq_daily()
.today()
.fetch()
.await?;
```
### KONEX 일별 시세
```rust
let data = client.stock()
.konex_daily()
.date("20240105")
.fetch()
.await?;
```
### 신주인수권 관련
```rust
// 신주인수권증권
let warrant = client.stock()
.stock_warrant_daily()
.today()
.fetch()
.await?;
// 신주인수권증서
let right = client.stock()
.stock_right_daily()
.today()
.fetch()
.await?;
```
### 종목 기본정보
```rust
// KOSPI 종목 정보
let kospi_info = client.stock()
.kospi_base_info()
.fetch()
.await?;
// KOSDAQ 종목 정보
let kosdaq_info = client.stock()
.kosdaq_base_info()
.fetch()
.await?;
// KONEX 종목 정보
let konex_info = client.stock()
.konex_base_info()
.fetch()
.await?;
```
## Index API
### KRX 지수
```rust
let krx_index = client.index()
.krx_daily()
.date("20240105")
.fetch()
.await?;
```
### KOSPI/KOSDAQ 지수
```rust
// KOSPI 지수
let kospi = client.index()
.kospi_daily()
.today()
.fetch()
.await?;
// KOSDAQ 지수
let kosdaq = client.index()
.kosdaq_daily()
.today()
.fetch()
.await?;
```
### 채권/파생상품 지수
```rust
// 채권지수
let bond_index = client.index()
.bond_daily()
.today()
.fetch()
.await?;
// 파생상품지수
let derivative_index = client.index()
.derivative_daily()
.today()
.fetch()
.await?;
```
## Bond API
### 국채 전문유통시장
```rust
let kts = client.bond()
.kts_daily()
.date("20240105")
.fetch()
.await?;
```
### 일반채권
```rust
let bond = client.bond()
.bond_daily()
.today()
.fetch()
.await?;
```
### 소액채권
```rust
let small_bond = client.bond()
.small_bond_daily()
.today()
.fetch()
.await?;
```
## ETP API
### ETF
```rust
let etf = client.etp()
.etf_daily()
.date("20240105")
.fetch()
.await?;
```
### ETN
```rust
let etn = client.etp()
.etn_daily()
.today()
.fetch()
.await?;
```
### ELW
```rust
let elw = client.etp()
.elw_daily()
.today()
.fetch()
.await?;
```
## Derivative API
### 선물
```rust
// 일반 선물
let futures = client.derivative()
.futures_daily()
.date("20240105")
.fetch()
.await?;
// 개별주식선물 (KOSPI)
let stock_futures = client.derivative()
.equity_stock_futures_daily()
.today()
.fetch()
.await?;
// 개별주식선물 (KOSDAQ)
let kosdaq_futures = client.derivative()
.equity_kosdaq_futures_daily()
.today()
.fetch()
.await?;
```
### 옵션
```rust
// 일반 옵션
let options = client.derivative()
.options_daily()
.date("20240105")
.fetch()
.await?;
// 개별주식옵션 (KOSPI)
let stock_options = client.derivative()
.equity_stock_options_daily()
.today()
.fetch()
.await?;
// 개별주식옵션 (KOSDAQ)
let kosdaq_options = client.derivative()
.equity_kosdaq_options_daily()
.today()
.fetch()
.await?;
```
## General API
### 유가
```rust
let oil = client.general()
.oil_daily()
.date("20240105")
.fetch()
.await?;
```
### 금
```rust
let gold = client.general()
.gold_daily()
.today()
.fetch()
.await?;
```
### 배출권
```rust
let emissions = client.general()
.emissions_daily()
.today()
.fetch()
.await?;
```
## ESG API
### SRI 채권 정보
```rust
let sri_bonds = client.esg()
.sri_bond_info()
.fetch()
.await?;
```
## DataFrame 활용
모든 API는 Polars DataFrame을 반환합니다:
```rust
let df = client.stock().kospi_daily().today().fetch().await?;
// 컬럼 확인
println!("컬럼: {:?}", df.get_column_names());
// 통계 정보
println!("평균 등락률: {:?}",
df.column("등락률")?.mean());
// 필터링
let rising_stocks = df.lazy()
.filter(col("등락률").gt(lit(0)))
.collect()?;
// 정렬
let top_gainers = df.lazy()
.sort("등락률", SortOptions::default().with_order_descending(true))
.limit(10)
.collect()?;
// CSV로 저장
df.write_csv("kospi_daily.csv")?;
```
## 빌더 패턴
모든 API는 빌더 패턴을 사용합니다:
```rust
// 기본 사용
let data = client.stock().kospi_daily().fetch().await?;
// 날짜 지정
let data = client.stock()
.kospi_daily()
.date("20240105")
.fetch()
.await?;
// 오늘 날짜
let data = client.stock()
.kospi_daily()
.today()
.fetch()
.await?;
```
## 비동기 처리
모든 API 호출은 비동기입니다:
```rust
// 동시에 여러 API 호출
let (kospi, kosdaq) = tokio::join!(
client.stock().kospi_daily().today().fetch(),
client.stock().kosdaq_daily().today().fetch()
);
let kospi_data = kospi?;
let kosdaq_data = kosdaq?;
```
## 오류 처리
상세한 오류 타입을 제공합니다:
```rust
use krx_rs::Error;
match client.stock().kospi_daily().fetch().await {
Ok(data) => println!("성공"),
Err(e) => match e {
Error::InvalidInput(msg) => println!("잘못된 입력: {}", msg),
Error::Network(e) => println!("네트워크 오류: {}", e),
Error::ApiError { status_code, message } => {
println!("API 오류 {}: {}", status_code, message)
}
Error::RateLimit { retry_after } => {
println!("요청 제한. {} 초 후 재시도", retry_after)
}
Error::Parsing { details, .. } => {
println!("파싱 오류: {}", details)
}
}
}
```