서울 아파트, 얼마나 올랐을까
국토교통부 실거래가로 서울 아파트의 기간별 상승률·변동폭과 동네 안에서의 순위를 보여주는 웹서비스.
기존 부동산 앱은 단지 하나의 시세 그래프는 잘 보여주지만, "내가 정한 기간 동안 이 단지가 얼마나 오르내렸고 그게 동네에서 몇 등인지"는 답해주지 않는다. 그 빈칸을 채우는 것이 목표다.
무엇을 볼 수 있나
| |
|---|
| 기간 자유 선택 | 2006년 1월 ~ 현재 사이 어느 구간이든 월 단위로 지정 |
| 네 가지 지표 | 기간 수익률 · 변동폭 · 고점 대비 · 저점 대비 |
| 동네 순위 | 선택한 구(또는 서울 전체) 안에서 몇 등인지 |
| 지도 | 오른 곳은 빨강, 내린 곳은 파랑. 점 크기는 거래량 |
| 대시보드 | 구별 비교, 수익률 분포, 변동폭×수익률 산점도, 연식별 비교, 고점 시점 분포 |
데이터
출처: 공공데이터포털 – 국토교통부 아파트 매매 실거래가 상세 자료
호가가 아니라 실제 체결된 신고가다. 2006년 1월부터 서울 25개 자치구 전량을 수집한다.
원시 거래 1,436,299건
정제 후 1,399,794건 (97.5%)
단지 9,255곳
집계 단지×월 497,571행
정제 규칙
| 규칙 | 이유 |
|---|
해제 거래(cdealType='O') 제외 | 허위 신고성 고가 거래가 고점을 오염시킨다 |
| 직거래 제외 | 증여성·특수관계 거래가 저점을 왜곡한다 |
토지임대부(landLeaseholdGbn='Y') 제외 | 소유 구조가 달라 평당가 비교가 불가능하다 |
| MAD 이상치(|z|>3.5) 제외 | 자릿수 오기입 제거. 하한 0.05를 둬서 정상 저층·대형 거래는 살린다 |
알아둘 한계
- 평당가는 전용면적 기준이다. 시중(네이버부동산 등)의 평당가는 대개 공급면적 기준이라 이 서비스의 숫자가 약 30% 높게 보인다.
- 최근 2개월은 신고 진행 중이라 값이 계속 바뀐다.
- 2020년 2월 이전에는 해제 신고 정보가 없다. 그 시기의 취소 거래는 걸러낼 수 없다.
- 좌표는 실거래가 API가 주지 않아 지번주소를 카카오 로컬 API로 변환해 채운다.
지표 정의
기간 [T0, T1], 시계열은 믹스 보정 지수 P(t) (만원/평, 전용).
수익률 P(T1) / P(T0) − 1
변동폭 P_max / P_min − 1 (시간 순서 무시)
고점 대비 P(T1) / P_max − 1 (≤ 0)
저점 대비 P(T1) / P_min − 1 (≥ 0)
최대 낙폭 min_t ( P(t) / 이전최고 − 1 ) (시간 순서 반영)
두 가지 설계 결정
① 면적 믹스 보정 — 없으면 변동폭 랭킹이 통째로 노이즈가 된다
같은 단지에서 3월엔 59㎡만, 4월엔 84㎡만 거래되면 가격이 전혀 변하지 않아도 한 달 만에 -11.5% 로 보인다. 소형이 평당가가 높기 때문이다.
이를 막기 위해 타입 고정효과를 2-pass로 추정해 걷어낸다.
m(c,b,t) = median{ ln(ppa) : 3개월 창 안의 버킷 b 거래 }
L0(c,t) = Σ w_b·m(c,b,t) / Σ w_b # 1차 (편향 있음)
δ_b = median_t { m(c,b,t) − L0(c,t) } # 타입 프리미엄
P(c,t) = exp( Σ w_b·(m − δ_b) / Σ w_b + Σ w_b·δ_b )
ln p = α_t + β_b + ε 헤도닉 회귀의 로버스트 근사다. median 만 쓰므로 희소 데이터에서 회귀보다 안정적이고 외부 의존성이 없다. 검증은 pipeline/tests/test_aggregate.py 참조.
② 시작·종료를 T0/T1 시점에 앵커한다
"기간 내 첫 거래월"을 시작가로 쓰면 A단지는 4년치, B단지는 1.5년치 수익률이 같은 표에서 경쟁하게 되어 랭킹이 구조적으로 거짓이 된다.
대신 T0/T1 시점에 고정하고, 그 달에 거래가 없으면 최대 6개월까지 이전 값을 끌어온다(캐리포워드). 미래 값을 끌어오는 캐리백워드는 2개월까지만 허용한다. 끌어온 거리(staleness)는 화면에 그대로 노출한다.
고점·저점은 실제 관측이 있는 달에서만 뽑는다. 캐리포워드로 평평해진 구간이 고점으로 잡히면 "거래가 없던 달이 고점"이라는 이상한 결과가 나온다.
순위 진입 조건
기간 내 거래 ≥ 5건 AND 관측된 달 ≥ 3개월
AND 앵커 노후도 ≤ 6개월 AND 생애 거래 ≥ 20건
단지 수로는 30% 남짓만 통과하지만, 그 30%가 실제 거래량의 84% 를 차지한다. 서울 아파트 상당수가 몇 년에 한 번 거래되는 소규모 단지이기 때문이다. 탈락한 단지도 목록 하단 접이식 섹션에서 찾을 수 있다.
구조
pipeline/ Python — 수집·정제·집계·익스포트
probe.py API 응답 구조 실측 (파서 작성 전 필수)
collect.py 수집 오케스트레이션 (증분·재개·쿼터 가드)
fetch.py HTTP (재시도·백오프·원시 XML 캐시)
clean.py 필터 + MAD 이상치
aggregate.py 믹스 보정 집계 ← 정확도의 핵심
metrics.py 지표 엔진 (참조 구현)
geocode.py 주소 → 좌표 (카카오 로컬 API)
export.py web/public/data/*.json 생성
web/ Next.js (App Router, 정적 export)
lib/metrics.ts pipeline/metrics.py 의 1:1 미러
lib/series.ts CSR 컬럼형 시계열 디코더
components/ 토스 스타일 UI · SVG 차트 · 카카오맵
계산은 100% 브라우저에서 한다. 기간이 자유로우니 서버라도 요청마다 전체를 훑어야 하고, 서버로 옮겨서 얻는 게 없다. 정적 JSON을 CDN에 올려두면 서버 비용도 장애 표면도 0이다.
pipeline/metrics.py 와 web/lib/metrics.ts 는 같은 골든 픽스처(pipeline/tests/fixtures/golden_metrics.json)로 검증한다. 두 구현이 갈라지면 테스트가 먼저 잡는다.
실행
준비물
# .env
DATA_GO_KR_KEY= # data.go.kr 일반 인증키 (Decoding)
KAKAO_REST_KEY= # 카카오 REST 키 (주소→좌표)
NEXT_PUBLIC_KAKAO_JS_KEY= # 카카오 JS 키 (지도)
카카오는 개발자 콘솔에서 [카카오맵] 활성화 설정을 ON 해야 한다. 지도와 로컬 API가 이 설정 하나에 묶여 있다.
데이터 파이프라인
python -m venv .venv && .venv/Scripts/python -m pip install -r pipeline/requirements.txt
export PYTHONPATH=pipeline
python pipeline/probe.py # API 응답 구조 확인
python pipeline/collect.py --all # 전량 수집 (약 6,200회 호출 / 30분)
python pipeline/build.py # 정제 + 집계
python pipeline/geocode.py # 좌표
python pipeline/export.py # JSON 생성
중단해도 fetch_log 를 보고 이어서 받는다. 원시 XML을 data/raw/ 에 보관하므로 파싱 로직을 바꿔도 API를 다시 때리지 않아도 된다 (--from-cache).
웹
cd web && npm install
npm run dev # http://localhost:3000
npm test # 지표 골든 테스트
테스트
.venv/Scripts/python -m pytest pipeline/tests/ -q # 지표 + 믹스 보정
cd web && npm test # TS 미러 검증
갱신
.github/workflows/weekly-update.yml 이 매주 월요일 05:00 KST 에 최신 실거래를 받아 재배포한다.
실거래 신고 기한이 계약일로부터 30일이라 과거 달의 데이터도 계속 늘어난다. 그래서 최근 4개월은 매번 다시 받는다. SQLite 원본(약 900MB)은 저장소에 둘 수 없어 Actions 캐시로 이어 붙이고, 캐시가 없으면 전량 백필로 자동 폴백한다.
저장소 Secrets 에 DATA_GO_KR_KEY, KAKAO_REST_KEY 를 등록해야 한다.
라이선스와 출처 표기
실거래가 데이터는 국토교통부가 공공데이터포털을 통해 제공한다. 이 서비스의 수치는 신고 기준이며 실제 시세와 차이가 있을 수 있다. 투자 판단의 근거로 삼기 전에 원본(실거래가 공개시스템)을 확인하기 바란다.
