한국 투자 증권 API 2) [국내주식] 종목정보

Tasker_Jang·2025년 3월 19일

국내주식 - 종목정보

한국투자증권 API는 풍부한 종목 정보와 재무 데이터를 제공하여 다양한 종목 분석이 가능합니다. 이 중 국내주식 종목정보 API를 활용한 효과적인 종목 분석 에이전트 개발 전략을 알아보겠습니다.

주요 API 소개

1. 상품 및 종목 기본 정보

상품기본조회 API와 주식기본조회 API를 통해 종목의 기본 정보를 수집할 수 있습니다.

{
  "pdno": "00000A000660",
  "prdt_type_cd": "300",
  "mket_id_cd": "STK",
  "scty_grp_id_cd": "ST",
  "prdt_name": "에스케이하이닉스보통주",
  "prdt_abrv_name": "SK하이닉스",
  "setl_mmdd": "12",
  "lstg_stcn": "728002365",
  "cpta": "3657652050000",
  "papr": "5000",
  "idx_bztp_lcls_cd_name": "시가총액규모대",
  "idx_bztp_mcls_cd_name": "전기,전자",
  "std_idst_clsf_cd_name": "반도체 제조업"
}

2. 재무제표 분석

대차대조표 API와 손익계산서 API를 통해 종목의 재무 상태를 분석할 수 있습니다.

{
  "stac_yymm": "202312",
  "cras": "1959366.00",
  "fxas": "2599694.00",
  "total_aset": "4559060.00",
  "flow_lblt": "757195.00",
  "fix_lblt": "165087.00",
  "total_lblt": "922281.00",
  "cpfn": "8975",
  "total_cptl": "3636779.00"
}

{
  "stac_yymm": "202312",
  "sale_account": "2589355.00",
  "sale_cost": "1803886.00",
  "sale_totl_prfi": "785469",
  "bsop_prti": "65670.00",
  "op_prfi": "110063.00",
  "thtr_ntin": "154871.00"
}

3. 재무비율 분석

재무비율 API는 투자 판단에 핵심이 되는 재무 지표들을 제공합니다.

{
  "stac_yymm": "202312",
  "grs": "-14.33",
  "bsop_prfi_inrt": "-84.86",
  "ntin_inrt": "-72.17",
  "roe_val": "4.14",
  "eps": "2131.00",
  "sps": "38120",
  "bps": "52002.00",
  "rsrv_rate": "39256.91",
  "lblt_rate": "25.36"
}

4. 투자의견 분석

종목투자의견 API와 증권사별 투자의견 API를 통해 시장 전문가들의 평가를 확인할 수 있습니다.

{
  "stck_bsop_date": "20240527",
  "invt_opnn": "매수",
  "invt_opnn_cls_code": "2",
  "rgbf_invt_opnn": "매수",
  "mbcr_name": "SK",
  "hts_goal_prc": "105000",
  "stck_prdy_clpr": "75900",
  "stck_nday_esdg": "-29100",
  "nday_dprt": "-27.71"
}

주식 시장 분석 활용 방안

1. 종합 종목 정보 제공 기능

종목코드를 입력받아 해당 종목의 기본 정보, 재무 정보, 투자의견을 종합적으로 제공하는 기능을 구현합니다.

def get_stock_info(stock_code):
    # 기본 정보 조회
    basic_info = get_basic_info(stock_code)
    
    # 재무 정보 조회
    financial_info = get_financial_info(stock_code)
    
    # 투자의견 조회
    invest_opinion = get_invest_opinion(stock_code)
    
    # 종합 정보 구성
    return {
        "basic": basic_info,
        "financial": financial_info,
        "opinion": invest_opinion
    }

결과 예시:

{
  "basic": {
    "code": "005930",
    "name": "삼성전자",
    "market": "KOSPI",
    "industry": "전기,전자",
    "capital": "897000000000",
    "listed_shares": "5969782550"
  },
  "financial": {
    "recent_quarter": "202312",
    "assets": "4559060.00",
    "liabilities": "922281.00",
    "equity": "3636779.00",
    "sales": "2589355.00",
    "operating_profit": "65670.00",
    "net_profit": "154871.00"
  },
  "opinion": {
    "consensus": "매수",
    "target_price": "95000",
    "current_price": "75900",
    "upside_potential": "25.16%"
  }
}

2. 재무 건전성 평가 기능

대차대조표와 재무비율 API 데이터를 활용하여 종목의 재무 건전성을 평가하는 기능을 구현합니다.

결과 예시:

{
  "debt": {
    "debt_ratio": "25.36%",
    "industry_avg": "35.42%",
    "evaluation": "양호",
    "score": 8
  },
  "profitability": {
    "roe": "4.14%",
    "industry_avg": "6.25%",
    "evaluation": "보통",
    "score": 5
  },
  "growth": {
    "sales_growth": "-14.33%",
    "profit_growth": "-72.17%",
    "evaluation": "미흡",
    "score": 3
  },
  "overall": {
    "score": 5.3,
    "evaluation": "보통",
    "comment": "부채비율은 양호하나 성장성이 다소 미흡합니다."
  }
}

3. 투자 의견 컨센서스 분석 기능

여러 증권사의 투자 의견을 종합하여 컨센서스를 도출하는 기능을 구현합니다.

결과 예시:

{
  "distribution": {
    "매수": 15,
    "중립": 6,
    "매도": 2
  },
  "target_price": {
    "average": "95000",
    "median": "93500",
    "max": "110000",
    "min": "80000"
  },
  "consensus": {
    "rating": "매수",
    "confidence": "높음",
    "target_upside": "25.16%",
    "recent_changes": [
      {
        "date": "20240527",
        "firm": "SK",
        "previous": "매수",
        "current": "매수",
        "target_change": "+5000"
      }
    ]
  }
}

4. 종목 가치 평가 기능

재무 데이터와 시장 가격을 비교하여 종목의 가치를 평가하는 기능을 구현합니다.

결과 예시:

{
  "per": {
    "value": "35.62",
    "industry_avg": "28.15",
    "market_avg": "12.5",
    "evaluation": "고평가",
    "score": 4
  },
  "pbr": {
    "value": "1.46",
    "industry_avg": "1.32",
    "market_avg": "1.05",
    "evaluation": "적정가치",
    "score": 6
  },
  "industry_comparison": {
    "relative_per": "1.27",
    "relative_pbr": "1.11",
    "evaluation": "약간 고평가"
  },
  "value_evaluation": {
    "score": 5.0,
    "status": "적정가치에 근접",
    "comment": "현재 주가는 업종 평균 대비 약간 고평가되어 있습니다."
  }
}

5. 종합 분석 리포트 생성 기능

위의 모든 분석 결과를 종합하여 사용자가 이해하기 쉬운 분석 리포트를 생성하는 기능을 구현합니다.

결과 예시:

{
  "stock_summary": {
    "code": "005930",
    "name": "삼성전자",
    "current_price": "75900",
    "daily_change": "-500 (-0.65%)",
    "market": "KOSPI",
    "industry": "전기,전자",
    "market_cap": "453,106,515,545,000"
  },
  "financial_health": {
    "overall_score": 5.3,
    "evaluation": "보통",
    "strengths": ["부채비율 양호", "유보율 높음"],
    "weaknesses": ["최근 수익성 하락", "성장률 둔화"]
  },
  "investment_opinions": {
    "consensus": "매수",
    "target_price": "95000",
    "upside_potential": "25.16%",
    "opinion_count": {
      "매수": 15,
      "중립": 6,
      "매도": 2
    }
  },
  "value_assessment": {
    "overall": "적정가치에 근접",
    "score": 5.0,
    "metrics": {
      "per": "35.62 (업종평균 대비 +27%)",
      "pbr": "1.46 (업종평균 대비 +11%)",
      "dividend_yield": "2.11%"
    }
  },
  "recommendation": {
    "rating": "중립",
    "confidence": "중간",
    "summary": "현재 주가는 적정가치에 근접해 있으며, 증권사들의 컨센서스는 매수입니다. 부채비율은 양호하나 최근 성장성과 수익성이 다소 약화되고 있어 중립적 접근을 권장합니다.",
    "investment_horizon": "중장기",
    "risk_level": "중간"
  }
}

구현 시 고려사항

데이터 캐싱: API 호출 횟수를 줄이기 위해 데이터 캐싱 메커니즘을 도입
예외 처리: API 호출 실패나 데이터 누락에 대한 적절한 예외 처리 구현
데이터 시각화: 복잡한 재무 데이터를 이해하기 쉽게 차트나 그래프로 시각화
사용자 맞춤형 설정: 사용자의 투자 성향이나 관심 지표에 따라 분석 결과를 조정할 수 있는 기능 제공
주기적 업데이트: 재무 데이터와 투자의견 변화를 주기적으로 확인하고 알림 기능 구현

결론

한국투자증권 API의 종목정보 관련 API를 활용하면 종목의 기본 정보부터 재무 상태, 시장 평가까지 종합적인 분석이 가능합니다. 이러한 분석 결과를 바탕으로 투자자들에게 객관적이고 데이터에 기반한 투자 판단 근거를 제공할 수 있습니다. 특히 Market Analysis Agent 프로젝트에 StockAnalyzerNode를 추가하여 뉴스 데이터와 재무 데이터를 종합적으로 분석하는 시스템을 구축한다면 더욱 가치 있는 서비스가 될 것입니다.