stock-kis-collector/README.md

stock-kis-collector

한국 주식 분석 플랫폼의 KIS(한국투자증권) 시세/종목 수집 서비스. KIS Open API를 통해 주가, 시가총액, 종목 정보를 수집하고, PostgreSQL에 저장된 데이터를 조회하는 REST API를 제공합니다.

기능

• 종목 수집: KOSPI/KOSDAQ 시가총액 상위 종목 목록 수집
• 가격 수집: 현재가 + 일별 시세 수집 (OHLCV, 시가총액)
• 종목 조회 API: 검색, 시장 필터, 페이징 지원
• 종목 상세 API: 최근 30일 가격 + 밸류에이션 지표
• OAuth2 인증: AppKey/AppSecret → access token 자동 갱신 (24시간 TTL)
• 비동기 워커: Redis Streams 기반 작업 큐 소비

API 엔드포인트

메서드	경로	설명
GET	/health	서비스 상태
GET	/streams	Redis Stream 큐 길이
GET	/stocks	종목 목록 (검색, 필터, 페이징)
GET	/stocks/{stock_code}	종목 상세 (가격 + 밸류에이션)
POST	/collect/stocks	종목 목록 수집 트리거
POST	/collect/prices	가격 수집 트리거

GET /stocks 파라미터

파라미터	타입	기본값	설명
market	string	all	시장 필터 (all, KOSPI, KOSDAQ)
search	string	""	종목명/코드 검색 (ILIKE)
limit	int	100	한 페이지당 개수
offset	int	0	페이징 오프셋

요청 예시

# 종목 검색
curl "http://localhost:8002/stocks?search=삼성&market=KOSPI&limit=10"

# 종목 상세
curl http://localhost:8002/stocks/005930

# 가격 수집 트리거
curl -X POST http://localhost:8002/collect/prices \
  -H "Content-Type: application/json" \
  -d '{"stock_codes": ["005930", "000660"]}'

응답 예시

// GET /stocks
{
  "total": 1500,
  "stocks": [
    {
      "stock_code": "005930",
      "stock_name": "삼성전자",
      "market": "KOSPI",
      "sector": "전기전자",
      "close": 72000,
      "volume": 15000000,
      "market_cap": 429000000000000,
      "change_pct": 1.41
    }
  ]
}

// GET /stocks/{code}
{
  "stock_code": "005930",
  "stock_name": "삼성전자",
  "market": "KOSPI",
  "prices": [{"date": "2024-12-20", "open": 71500, "close": 72000, ...}],
  "valuation": {"per": 12.5, "pbr": 1.1, "roe": 8.7, "debt_ratio": 28.3, ...}
}

데이터 파이프라인

POST /collect/stocks or /collect/prices
        │
        ▼
  queue:trigger-kis  ──→  Worker (KISCollector)
                                  │
                          ┌───────┴───────┐
                          ▼               ▼
                  queue:raw-stocks   queue:raw-prices

KIS API 세부사항

항목	값
Base URL (실전)	https://openapi.koreainvestment.com:9443
Base URL (모의)	https://openapivts.koreainvestment.com:9443
인증	OAuth2 (AppKey + AppSecret → Bearer token)
토큰 유효기간	24시간
Rate Limit	초당 20건
종목 목록	FHPST01740000 (시가총액 랭킹)
현재가	FHKST01010100 (주식현재가 조회)
일별 시세	FHKST03010100 (일별차트 조회)

프로젝트 구조

stock-kis-collector/
├── pyproject.toml
├── Dockerfile
├── .dockerignore
└── src/stock_kis_collector/
    ├── __init__.py
    ├── api.py          # FastAPI 엔드포인트 (GET + POST)
    ├── collector.py    # KISCollector (KIS API 호출, OAuth2)
    └── worker.py       # Redis Stream 소비자 + API 서버 실행

환경변수

변수	설명	기본값
KIS_APP_KEY	KIS 앱 키	(필수)
KIS_APP_SECRET	KIS 앱 시크릿	(필수)
KIS_BASE_URL	KIS API 베이스 URL	https://openapi.koreainvestment.com:9443
REDIS_URL	Redis 연결 URL	redis://localhost:6379/0
POSTGRES_HOST	PostgreSQL 호스트	localhost

로컬 실행

pip install -e ../stock-common && pip install -e .
python -m stock_kis_collector.worker

의존성

• stock-common - 공유 라이브러리
• Python >= 3.12