코스피 지수 시뮬레이터
전일 종가 기준 코스피 구성종목 데이터를 불러와, 특정 종목의 가격을 임의로
바꿨을 때 코스피 지수가 어떻게 변하는지 보여주는 조회 전용 시뮬레이터입니다.
로그인이나 매수/매도 기능은 없습니다.
동작 방식
- 사용자가 "최신화" 버튼을 누르면
/api/kospi 라우트가 실행됩니다.
- 이 라우트는 그 시점에 data.go.kr을 호출하는 얇은 프록시로, 별도의 DB·캐시·
크론 작업 없이 요청 시점의 데이터를 그대로 전달합니다.
금융위원회_지수시세정보에서 최근 영업일의 실제 코스피 종가(지수)를 가져옵니다
(휴일/주말 대비 최근 10일 이내에서 데이터가 있는 날짜를 자동으로 탐색합니다).금융위원회_주식시세정보에서 같은 기준일자의 전종목 시세를 가져와
시장구분이 KOSPI인 종목만 추립니다.기준시가총액 = 전체 시가총액 / (실제 코스피 지수 / 100) 공식으로
매일 기준시가총액을 역산(캘리브레이션)합니다.
- 브라우저는 응답받은 전종목 시세를 상태로 보관하고, 사용자가 특정 종목의
가격을 바꾸면 그 종목만 override된 시가총액으로 교체해 전체 합계와
시뮬레이션 코스피 지수를 즉시 재계산합니다. 나머지 계산은 모두
클라이언트에서 이뤄지며 서버 호출은 발생하지 않습니다.
환경변수
.env.local에 data.go.kr 일반 인증키(Decoding 값)를 설정합니다.
DATA_GO_KR_SERVICE_KEY=발급받은_디코딩_키
⚠️ 아래 두 API 모두 data.go.kr에서 개별적으로 활용신청이 되어 있어야 합니다.
같은 계정이면 서비스키는 동일하지만, API마다 활용신청 절차는 따로 필요합니다.
- 금융위원회_주식시세정보 (
GetStockSecuritiesInfoService)
- 금융위원회_지수시세정보 (
GetMarketIndexInfoService) — 코스피 지수 캘리브레이션에 필요
로컬 실행
npm install
npm run dev
http://localhost:3000 접속 후 "데이터 불러오기" 버튼을 누르면
API가 정상 동작하는지 확인할 수 있습니다.
배포 (Vercel)
- GitHub 저장소를 Vercel 프로젝트로 연결합니다.
- Vercel 프로젝트 설정 → Environment Variables에
DATA_GO_KR_SERVICE_KEY를 등록합니다.
(클라이언트에 노출되지 않는 서버 전용 환경변수입니다.)
- 별도의 DB, Blob/KV 스토리지, Cron Job 설정은 필요하지 않습니다.
알려진 제약
- data.go.kr 개발계정은 하루 10,000건 트래픽 제한이 있습니다. "최신화" 클릭 1회당
API 호출이 여러 번(지수 1회 + 종목 시세 페이지네이션 수회) 발생하므로, 트래픽이
늘어나면 운영계정 전환이나 클릭 디바운스를 검토해야 합니다.
- 데이터는 전일 종가 기준이며 장중 실시간 시세가 아닙니다.
mrktCtg가 KOSPI인 전종목을 지수 구성종목으로 간주하는 근사치이며,
KRX의 공식 지수 산출 방법론(우선주/제외종목 처리 등)과 완전히 일치하지
않을 수 있습니다. 투자 판단에 사용할 수 없는 교육·시뮬레이션 목적의 도구입니다.
