kfcc-Rates-Api

🏦 μƒˆλ§ˆμ„κΈˆκ³  금리 크둀러

μƒˆλ§ˆμ„κΈˆκ³ (KFCC) μ›Ήμ‚¬μ΄νŠΈμ—μ„œ 금리 정보와 κ²½μ˜μ‹€νƒœν‰κ°€ 데이터λ₯Ό μžλ™μœΌλ‘œ μˆ˜μ§‘ν•˜μ—¬ JSON API둜 μ œκ³΅ν•˜λŠ” Python ν¬λ‘€λŸ¬μž…λ‹ˆλ‹€.

✨ μ£Όμš” κΈ°λŠ₯

πŸ“Š 금리 정보 μˆ˜μ§‘

πŸ† κ²½μ˜μ‹€νƒœν‰κ°€ μˆ˜μ§‘

πŸ€– μžλ™ν™”

πŸš€ λΉ λ₯Έ μ‹œμž‘

1. μ €μž₯μ†Œ 클둠

git clone https://github.com/hosoodev/kfcc-Rates-Api.git
cd kfcc-Rates-Api/backend

2. μ˜μ‘΄μ„± μ„€μΉ˜

pip install -r requirements.txt

3. 크둀링 μ‹€ν–‰

# κΈ°λ³Έ 크둀링 (μ œμ£Όλ„λ§Œ)
python src/main.py

# 전체 지역 크둀링 (config.pyμ—μ„œ 주석 ν•΄μ œ)
python src/main.py

# 30일 이상 된 데이터 μ •λ¦¬ν•˜λ©° 크둀링
python src/main.py --cleanup 30

# 톡계 μ •λ³΄λ§Œ 좜λ ₯
python src/main.py --stats

# κ²½μ˜μ‹€νƒœν‰κ°€ μˆ˜μ§‘ (1μ›”, 7μ›”μ—λ§Œ)
python src/main.py --grades

πŸ“ ν”„λ‘œμ νŠΈ ꡬ쑰

backend/
β”œβ”€β”€ src/
β”‚   β”œβ”€β”€ main.py              # 메인 μ‹€ν–‰ 파일
β”‚   β”œβ”€β”€ config.py            # μ„€μ • 파일
β”‚   β”œβ”€β”€ crawler.py           # 금리 크둀러
β”‚   β”œβ”€β”€ grade_crawler.py     # κ²½μ˜μ‹€νƒœν‰κ°€ 크둀러
β”‚   β”œβ”€β”€ parser.py            # HTML νŒŒμ„œ
β”‚   └── storage.py           # 데이터 μ €μž₯ 관리
β”œβ”€β”€ data/
β”‚   β”œβ”€β”€ banks.json           # 은행 λͺ©λ‘
β”‚   β”œβ”€β”€ summary.json         # μš”μ•½ 톡계
β”‚   β”œβ”€β”€ rates/               # 일별 금리 데이터
β”‚   β”‚   β”œβ”€β”€ 2025-09-15.json
β”‚   β”‚   └── ...
β”‚   └── grades/              # κ²½μ˜μ‹€νƒœν‰κ°€ 데이터
β”‚       β”œβ”€β”€ grades_2025_06.json  # 6μ›” 평가 (7μ›” 15일 μˆ˜μ§‘)
β”‚       └── grades_2025_12.json  # 12μ›” 평가 (1μ›” 15일 μˆ˜μ§‘)
β”œβ”€β”€ .github/workflows/
β”‚   β”œβ”€β”€ crawler.yml          # 메인 크둀링 μ›Œν¬ν”Œλ‘œμš°
β”‚   └── grade-crawler.yml    # κ²½μ˜μ‹€νƒœν‰κ°€ μ›Œν¬ν”Œλ‘œμš°
β”œβ”€β”€ scripts/
β”‚   β”œβ”€β”€ restore-july-schedule.py  # 7μ›” μŠ€μΌ€μ€„ 볡원
β”‚   └── restore-july-schedule.md  # 볡원 κ°€μ΄λ“œ
└── requirements.txt         # Python μ˜μ‘΄μ„±

πŸ“Š 데이터 ν˜•μ‹

금리 데이터 μ˜ˆμ‹œ

{
  "metadata": {
    "date": "2025-09-15",
    "total_banks": 74,
    "successful_banks": 74,
    "crawled_at": "2025-09-15T21:33:04.455000",
    "version": "1.1"
  },
  "summary": {
    "total_banks": 74,
    "total_products": 292,
    "average_rate": 1.33,
    "min_rate": 0.01,
    "max_rate": 3.5,
    "rate_range": {
      "min": 0.01,
      "max": 3.5
    },
    "duration_stats": {
      "0": {
        "count": 135,
        "average_rate": 0.11,
        "min_rate": 0.01,
        "max_rate": 1.0
      },
      "12": {
        "count": 116,
        "average_rate": 2.5,
        "min_rate": 1.6,
        "max_rate": 3.1
      }
    },
    "product_type_stats": {
      "μš”κ΅¬λΆˆμ˜ˆνƒκΈˆ": {
        "count": 135,
        "average_rate": 0.11,
        "min_rate": 0.01,
        "max_rate": 1.0
      }
    }
  },
  "rates": [
    {
      "bank": {
        "gmgoCd": "6705",
        "name": "λ²•ν™˜(본점)",
        "city": "제주",
        "district": "μ„œκ·€ν¬μ‹œ",
        "phone": "064-739-1234",
        "address": "제주 μ„œκ·€ν¬μ‹œ μ€‘μ•™λ‘œ 123"
      },
      "base_date": "2025-09-15",
      "products": [
        {
          "product_name": "μ˜¨λΌμΈμžλ¦½μ˜ˆνƒκΈˆ",
          "duration_months": 0,
          "interest_rate": 0.1,
          "duration_text": "",
          "rate_text": "0.10%",
          "product_type": "μš”κ΅¬λΆˆμ˜ˆνƒκΈˆ"
        }
      ],
      "crawled_at": "2025-09-15T21:33:08.829000",
      "total_products": 2
    }
  ]
}

κ²½μ˜μ‹€νƒœν‰κ°€ 데이터 μ˜ˆμ‹œ

{
  "collection_info": {
    "collected_at": "2025-07-15T02:00:00.000000",
    "total_banks": 41,
    "evaluation_year": 2025,
    "evaluation_month": 6
  },
  "grades": [
    {
      "gmgo_cd": "6705",
      "bank_name": "λ²•ν™˜(본점)",
      "city": "제주",
      "district": "μ„œκ·€ν¬μ‹œ",
      "evaluation_agency": "λ²•ν™˜μƒˆλ§ˆμ„κΈˆκ³ ",
      "evaluation_date": "20250630",
      "grade_code": "2",
      "grade_name": "μ–‘ν˜Έ",
      "grade_description": "κ²½μ˜μƒνƒœκ°€ μ–‘ν˜Έν•œ μƒνƒœ",
      "collected_at": "2025-07-15T02:00:00.000000",
      "evaluation_year": 2025,
      "evaluation_month": 6
    }
  ]
}

은행 λͺ©λ‘ 데이터 μ˜ˆμ‹œ

{
  "collection_info": {
    "collected_at": "2025-09-15T21:30:00.000000",
    "total_banks": 3000,
    "regions": 17,
    "version": "1.1"
  },
  "banks": [
    {
      "gmgoCd": "6705",
      "name": "λ²•ν™˜(본점)",
      "city": "제주",
      "district": "μ„œκ·€ν¬μ‹œ",
      "phone": "064-739-1234",
      "address": "제주 μ„œκ·€ν¬μ‹œ μ€‘μ•™λ‘œ 123",
      "region": "제주"
    }
  ]
}

μš”μ•½ 톡계 데이터 μ˜ˆμ‹œ

{
  "total_banks": 3000,
  "total_products": 12000,
  "average_rate": 2.15,
  "min_rate": 0.01,
  "max_rate": 4.5,
  "rate_range": {
    "min": 0.01,
    "max": 4.5
  },
  "duration_stats": {
    "0": {
      "count": 5000,
      "average_rate": 0.15,
      "min_rate": 0.01,
      "max_rate": 1.2
    },
    "12": {
      "count": 4000,
      "average_rate": 2.8,
      "min_rate": 1.5,
      "max_rate": 4.0
    },
    "24": {
      "count": 3000,
      "average_rate": 3.2,
      "min_rate": 2.0,
      "max_rate": 4.5
    }
  },
  "product_type_stats": {
    "μš”κ΅¬λΆˆμ˜ˆνƒκΈˆ": {
      "count": 5000,
      "average_rate": 0.15,
      "min_rate": 0.01,
      "max_rate": 1.2
    },
    "κ±°μΉ˜μ‹μ˜ˆνƒκΈˆ": {
      "count": 4000,
      "average_rate": 2.8,
      "min_rate": 1.5,
      "max_rate": 4.0
    },
    "μ λ¦½μ‹μ˜ˆνƒκΈˆ": {
      "count": 3000,
      "average_rate": 2.5,
      "min_rate": 1.0,
      "max_rate": 3.8
    }
  },
  "crawled_at": "2025-09-15T21:30:00.000000"
}

βš™οΈ μ„€μ •

지역 μ„€μ • (config.py)

REGIONS = {
    "μ„œμšΈ": ["도봉ꡬ", "마포ꡬ", "관악ꡬ", ...],
    "인천": ["κ°•ν™”κ΅°", "μ„œκ΅¬", "동ꡬ", ...],
    "κ²½κΈ°": ["κΉ€ν¬μ‹œ", "νŒŒμ£Όμ‹œ", "μ—°μ²œκ΅°", ...],
    # ... λͺ¨λ“  μ‹œ/도
}

크둀링 μ„€μ •

CRAWLER_CONFIG = {
    'timeout': 10,              # μš”μ²­ νƒ€μž„μ•„μ›ƒ (초)
    'max_workers_list': 5,      # 은행 λͺ©λ‘ μˆ˜μ§‘ μ›Œμ»€ 수
    'max_workers_rate': 10,     # 금리 μˆ˜μ§‘ μ›Œμ»€ 수
    'retry_count': 3,           # μž¬μ‹œλ„ 횟수
    'retry_delay': 1            # μž¬μ‹œλ„ 간격 (초)
}

κ²½μ˜μ‹€νƒœν‰κ°€ μ„€μ •

GRADE_CONFIG = {
    'enabled': True,            # μˆ˜μ§‘ ν™œμ„±ν™”
    'collection_month': [1, 7], # μˆ˜μ§‘ μ›” (1μ›” 15일, 7μ›” 15일)
    'evaluation_year': 2025,    # 평가 연도 (당해년도 μžλ™)
    'evaluation_month': [6, 12], # 평가 κΈ°μ€€ μ›” (6μ›”, 12μ›”)
    'retry_count': 3,
    'retry_delay': 1,
    'timeout': 10
}

πŸ”§ μ‚¬μš©λ²•

λͺ…λ Ήν–‰ μ˜΅μ…˜

python src/main.py [μ˜΅μ…˜]

μ˜΅μ…˜:
  --cleanup DAYS     μ§€μ •λœ 일수 이상 된 데이터 정리
  --stats            μ €μž₯μ†Œ 톡계 μ •λ³΄λ§Œ 좜λ ₯
  --grades           κ²½μ˜μ‹€νƒœν‰κ°€ 데이터 μˆ˜μ§‘ (1μ›”, 7μ›”μ—λ§Œ)
  --help             도움말 좜λ ₯
  --version          버전 정보 좜λ ₯

ν™˜κ²½λ³€μˆ˜

# κ²½μ˜μ‹€νƒœν‰κ°€ κ°•μ œ μ‹€ν–‰ (μ›” μ œν•œ λ¬΄μ‹œ)
export FORCE_GRADE_COLLECTION=true
python src/main.py --grades

πŸ“… μŠ€μΌ€μ€„

μžλ™ μ‹€ν–‰

μˆ˜λ™ μ‹€ν–‰

πŸ› οΈ 개발

μ˜μ‘΄μ„±

requests>=2.31.0
beautifulsoup4>=4.12.0
python-dotenv>=1.0.0

개발 ν™˜κ²½ μ„€μ •

# κ°€μƒν™˜κ²½ 생성
python -m venv venv

# κ°€μƒν™˜κ²½ ν™œμ„±ν™” (Windows)
venv\Scripts\activate

# κ°€μƒν™˜κ²½ ν™œμ„±ν™” (Linux/Mac)
source venv/bin/activate

# μ˜μ‘΄μ„± μ„€μΉ˜
pip install -r requirements.txt

ν…ŒμŠ€νŠΈ

# κΈ°λ³Έ 크둀링 ν…ŒμŠ€νŠΈ
python src/main.py --stats

# κ²½μ˜μ‹€νƒœν‰κ°€ ν…ŒμŠ€νŠΈ (ν™˜κ²½λ³€μˆ˜ μ„€μ •)
export FORCE_GRADE_COLLECTION=true
python src/main.py --grades

πŸ“ˆ μ„±λŠ₯

μˆ˜μ§‘ μ„±λŠ₯

μ €μž₯μ†Œ 크기

πŸ”’ λ³΄μ•ˆ

πŸ“ λΌμ΄μ„ μŠ€

MIT License

🀝 κΈ°μ—¬

  1. Fork the Project
  2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
  3. Commit your Changes (git commit -m 'Add some AmazingFeature')
  4. Push to the Branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

πŸ“ž 지원

πŸ“‹ 체크리슀트

πŸ”„ μ—…λ°μ΄νŠΈ 둜그

v1.2.0 (2025-09-16)

v1.1.0 (2025-09-15)

v1.0.0 (2025-09-14)

⭐ 이 ν”„λ‘œμ νŠΈκ°€ 도움이 λ˜μ—ˆλ‹€λ©΄ Starλ₯Ό λˆŒλŸ¬μ£Όμ„Έμš”!