이건 무엇을 왜 어떻게 했는지를 남기는 작업 로그다. 각 API의 사용법 레퍼런스는 통합 레퍼런스에 따로 정리했고, 여기선 하루 동안 개인 데이터 도구를 한국 공공데이터 플랫폼으로 확장한 과정을 순서대로 남긴다.
⚠️ 안전 고지: 공개 정부 오픈데이터 API 구축 기록이다. 수치는 공표된 공개 통계(2026-05~06 기준)이며 투자·회계 자문이 아니다. 모든 키는
.env에만 두고 값은 기재하지 않는다.
0. 오늘 한 일 — 한눈에
| # | 단계 | 결과물(모듈) |
|---|---|---|
| 1 | 금리 전수 (한국은행 ECOS + 수출입은행) | fetch_rates.js |
| 2 | 부동산 통계 (한국부동산원 R-ONE) + KOSIS 평가 | lib_reb_api.js·fetch_reb*.js |
| 3 | 공시지가·주택공시가격 (V-World) | lib_vworld.js·fetch_realestate.js |
| 4 | 실거래가 12종 (data.go.kr MOLIT) | lib_molit_rt.js·fetch_region_trades.js |
| 5 | 지역 분석 (금천·서남권 3구) | 실거래 종합·추세 |
| 6 | 건축HUB 5종 (data.go.kr) | lib_bldreg.js + archhub MCP |
| 7 | 통합 레퍼런스 + 본 작업로그 | 문서화 |
신규 API 키 3종 확보 · 공용 모듈 5개 신규 · 수집기 9개 구축.
1. 확보한 API 키 (전부 .env, .gitignore — 값은 기록하지 않음)
| 변수 | 발급기관 | 형식 | 용도 |
|---|---|---|---|
KOREAEXIM_API_KEY | 한국수출입은행 | 32자 영숫자 | 환율·대출금리·국제금리 공통 1키 |
BOK_ECOS_API_KEY | 한국은행 ECOS | 대문자 영숫자 | 경제통계시스템 전체 |
REB_API_KEY | 한국부동산원 | 32자 hex | R-ONE 부동산통계 738표 |
VWORLD_API_KEY | 국토부 V-World | GUID | 공간정보·공시지가·주택공시가격 |
MOLIT_API_KEY | data.go.kr | Decoding(+·== 포함) | 실거래가 12종 + 건축HUB 5종 |
- MOLIT 키 하나로 실거래가 + 건축HUB 둘 다 사용(같은 data.go.kr 계정, API별 활용신청).
- data.go.kr은 Encoding/Decoding 2종 발급 → Decoding본을
.env에 넣고 코드가encodeURIComponent처리. Decoding 원본 무인코딩은 401.
2. 데이터 소스별 상세 — 어디서 무엇을 가져왔나
2-1. 한국은행 ECOS — 금리·통화·실물
- 가져온 것: 기준금리(722Y001)·시장금리 일별 12종(817Y002)·대출금리 신규/잔액(121Y006/015)·수신금리(121Y002)·연체율(901Y124)·대출행태서베이(514Y001~003)·100대지표
- 핵심 수치(공표): 기준금리 2.75%(7/16 인상), 국고3년 3.917%, 회사채 BBB− 10.408%, 대출평균 4.19%, 예대금리차 1.26%p
2-2. 한국수출입은행 — 환율·수은채·국제금리
- 가져온 것: 통화별 매매기준율, 수은채 유통수익률 커브(1M~10Y), SOFR·ESTR·EURIBOR·TIBOR·스왑·CIRR
- 핵심: USD 1,469.4원 · SOFR 3.62%(한·미 단기 역전 −94.5bp) · 수은채 10년 4.63%
2-3. 한국부동산원 R-ONE — 가격지수·거래·지가
- 수집기 신규:
fetch_reb_catalog.js(738표 카탈로그) ·fetch_reb.js(거래·지가) ·fetch_reb_price.js(유형별 가격) - 가져온 것: 아파트/연립/오피스텔 매매·전세 지수(2026-05/06), 지가변동률·지가지수, 유형별 거래량·연령대별
- 핵심(공표): 서울 아파트 매매지수 YoY +13.5%, 전세가율 서울 51.8%, 30대 아파트매매 32.4%
2-4. 국토부 V-World — 공시지가·주택공시가격·토지특성
- 가져온 것: 지오코딩(주소→좌표+법정동), 필지조회(좌표→PNU), 개별공시지가·토지특성·개별주택가격·공동주택가격
- 수집기 신규:
fetch_realestate.js "<주소>"→ 공시지가 5개년+토지특성+주택공시가격 - 실측(공표 공시가격): 역삼동737 6,730만원/㎡ · 은마 84㎡ 공시 20.63억 · 가회동 단독 6.16억
2-5. 국토부 실거래가 (data.go.kr) — 12유형
- 12종 전량 작동 검증: 아파트/연립/단독다가구/오피스텔 매매·전월세 + 분양권·토지·상업업무용·공장창고
- 수집기 신규:
fetch_region_trades.js <LAWD> "<지역>" [개월](8유형 종합) ·fetch_region_trend.js(월별 추세)
2-6. 국토부 건축HUB (data.go.kr) — 5종 ★전부 작동
- 5종: 건축물대장
BldRgstHubService·건축인허가ArchPmsHubService·주택인허가HsPmsHubService·건물에너지BldEngyHubService·폐쇄말소ShtRgstHubService - 실측(공개 건축물): 은마 표제부 31건(29동)·금천독산 인허가 7,141건·주택인허가 308건·폐쇄말소 7,663건·은마 전기사용량(useYm)
- archhub MCP 병행:
find_region→building_profile→permits_pipeline등
2-7. KOSIS (korean-stats MCP) — 검색·발견 + 고유통계
- 역할: 금리·부동산은 원기관 미러라 갱신 지연 → 검색·발견 도구로만 사용,
orgId/tableId확보 후 원기관 직결 - KOSIS 고유: 가계금융복지조사(소득/자산 분위별 부채·금액), 주택보급률, 중견기업 대출금리
3. 구축한 코드 자산
공용 모듈 (lib)
| 파일 | 대상 | 특징 |
|---|---|---|
lib_finance_api.js | ECOS·수출입은행 | (기존) statisticSearch·getExim |
lib_reb_api.js | 부동산원 R-ONE | 신규 · 400ms 직렬 스로틀·페이지네이션 |
lib_vworld.js | V-World | 신규 · 지오코더·필지·공시가격 |
lib_molit_rt.js | 실거래가 | 신규 · 12서비스·403/401 감지 |
lib_bldreg.js | 건축HUB | 신규 · 5서비스·PNU변환·XML파싱 |
수집기 (fetch)
fetch_rates.js(ECOS 금리) · fetch_macro_data.js(수출입) · fetch_reb_catalog.js · fetch_reb.js · fetch_reb_price.js · fetch_realestate.js(V-World+실거래가) · fetch_region_trades.js · fetch_region_trend.js
4. 주요 분석 발견 (공개 데이터 기반)
- 금리: 기준금리 인상은 단기금리가 하루 만에 흡수, 장기금리는 유가(브렌트 100달러)가 밀어올림(베어 스티프닝). 회사채 BBB− 10.4%로 비우량 조달시장이 사실상 얼어붙은 상태.
- 부동산 유형×지역 이중 양극화: 서울 아파트(+13.5%)≫빌라(+8.8%)≫오피스텔(+0.9%), 서울≫수도권≫지방. 30대가 서울 아파트 매수 주도(32.4%).
- 금천구: 서울 실거주 최저선(아파트 중위 6.2억). 오피스텔 전세가율이 매매가를 넘는 구간이 관측됨(물건집합 차이에 따른 표면값 유의). 다가구·오피스텔 월세 지배.
- 서남권 3구: 관악(봉천 신축대)·구로(신도림~개봉 편차 큼)·금천(최저·균질). 3구 공통 오피스텔 전세가율 100%+ 표면값.
- 거래량 vs 공급: 금천 아파트 거래량 5월 정점(170건) 후 6월 꺾임 + 가격 보합 = 관망. 건축HUB 인허가로 신규 아파트 공급 파이프라인 빈약(대형 신축 0·미착공 위주) 확인 → “공급 부족 + 수요 관망”이 겹친 국면. 실거래가만으론 못 가르는 걸 건축HUB로 판별.
⚠️ 위 분석은 공개 데이터 기반의 방법론·관찰이며 특정 지역·시점의 투자 판단이 아니다.
5. 트러블슈팅 로그 — 실제로 겪고 해결한 함정
| # | 증상 | 원인 | 해결 |
|---|---|---|---|
| 1 | REB 거래량 MoM −92% 허수 | ITM_ID 미지정 시 동호수·면적 혼입 | ITM_ID=100001 고정 |
| 2 | REB “경기 580호” 비현실 | 표마다 지역 CLS_ID 다름(500009=세종) | 표별 ITM_TAG=분류 확인 |
| 3 | REB 가격지수 “끊긴 줄” | pIndex=1은 오래된순·DATA_END_YY 부정확 | START/END_WRTTIME 창 조회 |
| 4 | REB 서울 평균가 577만(실은 인천) | 표마다 서울코드 다름 | 표별 코드맵 |
| 5 | ECOS 서베이 전부 INFO-200 | 표별 접두 상이(태도AA·위험BB·수요CC) | 접두 분기 |
| 6 | ECOS 연체율 값 섞임 | 901Y124 2차원(대출종류×은행종류) | itemCode1+2 |
| 7 | MOLIT 발급직후 403 Forbidden | 키 오류 아님 — API별 활성화 전파지연 | 수분 후 재시도(5/12→12/12) |
| 8 | MOLIT Decoding키 401 | 무인코딩 사용 | encodeURIComponent |
| 9 | 건축HUB 200인데 빈응답(len=0) | _type=json이 일부 서비스서 빈응답 | _type 생략(XML)+XML파싱 |
| 10 | 건축HUB 주택인허가 404 | 서비스명 오추정(HsPmsService) | HsPmsHubService/getHp* |
| 11 | 건축HUB 폐쇄말소 500 | 서비스명 오추정(ClosBrHubService) | ShtRgstHubService/getSr* |
| 12 | 건물에너지 cnt=0 | useYm(사용연월) 필수 누락 | useYm=YYYYMM + bun/ji |
| 13 | V-World data API INVALID_RANGE | geomFilter/attrFilter 필수 | POINT 필터 |
6. 연결 구조 — 지역명 하나로 전부 잇기
지역명/주소 ──V-World 지오코더──▶ 좌표+법정동
좌표 ──V-World 필지조회──▶ PNU(19자리)
PNU 앞5자리 = LAWD_CD(실거래가) = sigunguCd(건축HUB)
├─ 공시지가·주택공시가격 (V-World /ned/)
├─ 실거래가 12유형 (data.go.kr 1613000)
└─ 건축물대장·인허가·에너지·폐쇄말소 (건축HUB 1613000)
→ 주소 하나 → 공시가격 + 실거래가 + 건축물대장 + 인허가가 모두 연결된다.
7. 후속 과제 (미완/제안)
- 건물에너지
useYm시계열 루프로 단지별 전기·가스 사용량 추세 수집기화. - 건축HUB 인허가·주택인허가 동별 연도별 공급량 정량화 → “공급 부족” 가설 수치 확정.
- 특정 단지 지정 → 그 단지 공시가격+실거래가+건축물대장 매칭.
- 서남권 5구 확대(+영등포·양천), 관악·구로 12개월 추세.
8. 검증·주의
- ✅ 실거래가 12/12·V-World 6종·ECOS·REB·건축HUB 5종 전부 실측 작동.
- ⚠️ 부동산 데이터 대부분 2026-05~06 기준.
- ⚠️ 실거래가 202607은 진행 중 월(신고 마감 전, 건수 적음).
- ⚠️ 중위가는 유형 내 평형·연식 혼재(동일평형 비교 아님).
- ⚠️ 모든 키는
.env에만(.gitignore), 문서·리포트에 값 미기재.
한 줄 회고: 흩어진 정부 API 예닐곱 개가 주소 하나 → PNU → 앞 5자리라는 공통 키로 한 화면에 모이는 순간이, 종일 삽질한 보람이었다.