Metadata-Version: 2.4
Name: openstock-kr
Version: 0.1.2
Summary: 한국거래소(KRX) OPEN API 기반 주식 데이터 수집 패키지
Author-email: HANHO <hanhoman@gmail.com>
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: pandas
Requires-Dist: requests

# openstock-kr

**openstock-kr**은 한국거래소(KRX) OPEN API를 파이썬 환경에서 쉽고 안정적으로 수집할 수 있도록 도와주는 라이브러리입니다. 

주식 시장의 지수, 종목별 시세, 종목 기본 정보 데이터를 몇 줄의 코드로 간단하게 수집하고, 분석에 바로 사용할 수 있도록 데이터 전처리(수치형 변환, 한글 컬럼명 매핑 등)를 자동화하여 제공합니다.

<br>

## ✨ 주요 기능
* **간편한 API 호출:** KOSPI, KOSDAQ 시장의 데이터를 한 번의 메서드 호출로 병합하여 가져옵니다.
* **자동 예외 처리:** 네트워크 지연, 서버 오류, 빈 데이터 응답 등의 예외 상황을 내부적으로 안전하게 처리합니다.
* **스마트한 수치형 변환:** 문자열로 섞여 들어오는 숫자 데이터(예: 콤마가 포함된 거래대금, '무액면' 문자가 포함된 액면가 등)를 판별하여 안전하게 `int` 또는 `float`으로 변환합니다.
* **컬럼명 언어 설정:** 분석 편의를 위해 원본 영문 컬럼명(`en`)과 번역된 한글 컬럼명(`kr`)을 선택할 수 있습니다. 

<br>

## 📦 설치 방법

```bash
pip install --upgrade openstock-kr
```

<br>

## 🔑 사전 준비

- 이 라이브러리를 사용하려면 [한국거래소 OPEN API(openapi.krx.co.kr)](https://openapi.krx.co.kr/)에서 무료로 발급하는 **OPEN API 인증키(AUTH_KEY)** 가 필요합니다.
- API 인증키 발급 이후, 다음의 API 서비스에 대해서 개별적으로 **API이용신청과 거래소 담당자 승인**이 완료되어야 합니다. (인증키만 발급받는 경우, API 서비스가 지원되지 않음) 
  - KRX 시리즈 일별시세정보
  - KOSPI 시리즈 일별시세정보
  - KOSDAQ 시리즈 일별시세정보
  - 유가증권 일별매매정보
  - 코스닥 일별매매정보
  - 유가증권 종목기본정보
  - 코스닥 종목기본정보

<br>

## 🚀 빠른 시작 (Quick Start)

### 1. 초기화

```python
from OpenStock import OpenStock

# 발급받은 API 키 입력
api_key = "YOUR_API_KEY_HERE"
stock = OpenStock(api_key=api_key)
```
<br>

### 2. 시장 지수 데이터 수집 (`get_index`)

특정 일자의 지수(KRX, KOSPI, KOSDAQ) 데이터를 수집합니다.

```python
# 기준일자 'YYYYMMDD' 형식 입력, col_lan='kr' 설정 시 한글 컬럼명 반환
df_index = stock.get_index('20260306', col_lan='kr')
print(df_index.head())
```

<table border="1" class="dataframe">
  <thead>
    <tr style="text-align: right;">
      <th></th>
      <th>기준일자</th>
      <th>계열구분</th>
      <th>지수명</th>
      <th>종가</th>
      <th>대비</th>
      <th>등락률</th>
      <th>시가</th>
      <th>고가</th>
      <th>저가</th>
      <th>거래량</th>
      <th>거래대금</th>
      <th>상장시가총액</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th>0</th>
      <td>20260306</td>
      <td>KRX</td>
      <td>코리아 밸류업 지수</td>
      <td>2527.38</td>
      <td>-5.00</td>
      <td>-0.20</td>
      <td>2485.89</td>
      <td>2540.04</td>
      <td>2437.12</td>
      <td>98491925</td>
      <td>19146024297629</td>
      <td>2871927789805430</td>
    </tr>
    <tr>
      <th>1</th>
      <td>20260306</td>
      <td>KRX</td>
      <td>KRX TMI</td>
      <td>3495.45</td>
      <td>5.95</td>
      <td>0.17</td>
      <td>3431.22</td>
      <td>3510.08</td>
      <td>3358.95</td>
      <td>1892509220</td>
      <td>43601448268843</td>
      <td>5038925260559923</td>
    </tr>
    <tr>
      <th>2</th>
      <td>20260306</td>
      <td>KRX</td>
      <td>KRX 300</td>
      <td>3727.16</td>
      <td>-1.82</td>
      <td>-0.05</td>
      <td>3661.71</td>
      <td>3745.96</td>
      <td>3583.89</td>
      <td>307812064</td>
      <td>32413529432980</td>
      <td>4571110141562820</td>
    </tr>
    <tr>
      <th>3</th>
      <td>20260306</td>
      <td>KRX</td>
      <td>KRX 중대형 TMI</td>
      <td>3549.75</td>
      <td>3.82</td>
      <td>0.11</td>
      <td>3484.93</td>
      <td>3565.55</td>
      <td>3411.35</td>
      <td>805377051</td>
      <td>37939022960371</td>
      <td>4839605918579618</td>
    </tr>
    <tr>
      <th>4</th>
      <td>20260306</td>
      <td>KRX</td>
      <td>KRX 중형 TMI</td>
      <td>2042.35</td>
      <td>65.94</td>
      <td>3.34</td>
      <td>1976.53</td>
      <td>2042.35</td>
      <td>1940.34</td>
      <td>497564987</td>
      <td>5525493527391</td>
      <td>268495777016798</td>
    </tr>
  </tbody>
</table>

<br>

### 3. 종목 시세 데이터 수집 (`get_price`)

특정 일자의 전 종목 시세(KOSPI, KOSDAQ) 데이터를 수집합니다.

```python
df_price = stock.get_price('20260306', col_lan='kr')
print(df_price.head())
```
<table border="1" class="dataframe">
  <thead>
    <tr style="text-align: right;">
      <th></th>
      <th>기준일자</th>
      <th>종목코드</th>
      <th>종목명</th>
      <th>시장구분</th>
      <th>소속부</th>
      <th>종가</th>
      <th>대비</th>
      <th>등락률</th>
      <th>시가</th>
      <th>고가</th>
      <th>저가</th>
      <th>거래량</th>
      <th>거래대금</th>
      <th>시가총액</th>
      <th>상장주식수</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th>0</th>
      <td>20260306</td>
      <td>095570</td>
      <td>AJ네트웍스</td>
      <td>KOSPI</td>
      <td></td>
      <td>4960</td>
      <td>20</td>
      <td>0.40</td>
      <td>4925</td>
      <td>5010</td>
      <td>4825</td>
      <td>180901</td>
      <td>890216366</td>
      <td>224453684640</td>
      <td>45252759</td>
    </tr>
    <tr>
      <th>1</th>
      <td>20260306</td>
      <td>006840</td>
      <td>AK홀딩스</td>
      <td>KOSPI</td>
      <td></td>
      <td>8050</td>
      <td>40</td>
      <td>0.50</td>
      <td>8170</td>
      <td>8170</td>
      <td>7820</td>
      <td>9714</td>
      <td>77138585</td>
      <td>106642866050</td>
      <td>13247561</td>
    </tr>
    <tr>
      <th>2</th>
      <td>20260306</td>
      <td>027410</td>
      <td>BGF</td>
      <td>KOSPI</td>
      <td></td>
      <td>4115</td>
      <td>-85</td>
      <td>-2.02</td>
      <td>4190</td>
      <td>4190</td>
      <td>4045</td>
      <td>181608</td>
      <td>741963097</td>
      <td>393874594965</td>
      <td>95716791</td>
    </tr>
    <tr>
      <th>3</th>
      <td>20260306</td>
      <td>282330</td>
      <td>BGF리테일</td>
      <td>KOSPI</td>
      <td></td>
      <td>115000</td>
      <td>-300</td>
      <td>-0.26</td>
      <td>113600</td>
      <td>116900</td>
      <td>113600</td>
      <td>64886</td>
      <td>7459422856</td>
      <td>1987649190000</td>
      <td>17283906</td>
    </tr>
    <tr>
      <th>4</th>
      <td>20260306</td>
      <td>138930</td>
      <td>BNK금융지주</td>
      <td>KOSPI</td>
      <td></td>
      <td>18420</td>
      <td>-380</td>
      <td>-2.02</td>
      <td>18190</td>
      <td>18580</td>
      <td>18090</td>
      <td>921541</td>
      <td>16892012835</td>
      <td>5716223947860</td>
      <td>310327033</td>
    </tr>
  </tbody>
</table>

<br>


### 4. 종목 기본 정보 수집 (`get_stockinfo`)

특정 일자의 종목 기본 정보(표준코드, 액면가, 상장주식수 등) 데이터를 수집합니다.

```python
df_info = stock.get_stockinfo('20260306', col_lan='kr')
print(df_info.head())
```
<table border="1" class="dataframe">
  <thead>
    <tr style="text-align: right;">
      <th></th>
      <th>표준코드</th>
      <th>단축코드</th>
      <th>한글종목명</th>
      <th>한글종목약명</th>
      <th>영문종목명</th>
      <th>상장일</th>
      <th>시장구분</th>
      <th>증권구분</th>
      <th>소속부</th>
      <th>주식종류</th>
      <th>액면가</th>
      <th>상장주식수</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th>0</th>
      <td>KR7095570008</td>
      <td>095570</td>
      <td>AJ네트웍스보통주</td>
      <td>AJ네트웍스</td>
      <td>AJ Networks Co.,Ltd.</td>
      <td>20150821</td>
      <td>KOSPI</td>
      <td>주권</td>
      <td></td>
      <td>보통주</td>
      <td>1000</td>
      <td>45252759</td>
    </tr>
    <tr>
      <th>1</th>
      <td>KR7006840003</td>
      <td>006840</td>
      <td>AK홀딩스보통주</td>
      <td>AK홀딩스</td>
      <td>AK Holdings, Inc.</td>
      <td>19990811</td>
      <td>KOSPI</td>
      <td>주권</td>
      <td></td>
      <td>보통주</td>
      <td>5000</td>
      <td>13247561</td>
    </tr>
    <tr>
      <th>2</th>
      <td>KR7282330000</td>
      <td>282330</td>
      <td>BGF리테일보통주</td>
      <td>BGF리테일</td>
      <td>BGF Retail</td>
      <td>20171208</td>
      <td>KOSPI</td>
      <td>주권</td>
      <td></td>
      <td>보통주</td>
      <td>1000</td>
      <td>17283906</td>
    </tr>
    <tr>
      <th>3</th>
      <td>KR7027410000</td>
      <td>027410</td>
      <td>BGF보통주</td>
      <td>BGF</td>
      <td>BGF</td>
      <td>20140519</td>
      <td>KOSPI</td>
      <td>주권</td>
      <td></td>
      <td>보통주</td>
      <td>1000</td>
      <td>95716791</td>
    </tr>
    <tr>
      <th>4</th>
      <td>KR7138930003</td>
      <td>138930</td>
      <td>BNK금융지주보통주</td>
      <td>BNK금융지주</td>
      <td>BNK Financial Group Inc.</td>
      <td>20110330</td>
      <td>KOSPI</td>
      <td>주권</td>
      <td></td>
      <td>보통주</td>
      <td>5000</td>
      <td>310327033</td>
    </tr>
  </tbody>
</table>

<br>

## 📝 라이선스 (License)

This project is licensed under the MIT License.
