# 호가(HOGA) — 서울 아파트 실거래가

> 국토교통부 실거래가 공개시스템 기반. 2006년~현재까지 서울 25개 자치구 아파트 매매 실거래가 데이터.

## 제공 데이터
- 서울 아파트 매매 실거래가 (2006년 1월 ~ 현재)
- 25개 자치구, 400+ 법정동, 5,000+ 아파트 단지
- 거래금액, 전용면적, 층, 건축년도, 거래유형, 해제여부

## 분석 기능
- 단지별 가격 추이 (년도별/월별)
- 층별 가격 분석 (저층/중층/고층/초고층 프리미엄)
- 평형별 시세 (소형/국민평형/중대형/대형)
- 가격 분산도 (면적별 중위가/IQR)
- 계절 패턴 (몇 월에 가장 싸고 비싼지)
- 거래 가격 편차 분류 (일반/중위가 대비 저가/중위가 대비 고가)
- 고점 대비 낙폭
- 대장 아파트 대비 할인율
- 매수 타이밍 시그널 (관망/저점접근/회복초기/가속상승/과열주의)
- 시장 사이클 (구별 상승/과열/회복/하락)
- 이상 거래 감지 (급등/급락, 해제비율, 단기반복)

## API 엔드포인트
Base URL: https://hoga.pages.dev/api/v1

- GET /trades — 거래 조회 (필터: gu, dong, name, year, price, area)
- GET /search?q= — 아파트명 검색
- GET /autocomplete?q= — 자동완성 (pg_trgm 퍼지)
- GET /rankings — 단지 랭킹 (type: price_up, price_down, volume_surge, value, peak_drop, new_high)
- GET /stats — 통계 요약
- GET /top?n= — 최고가 TOP N
- GET /trend — 월별 가격 추이
- GET /compare?names= — 단지 비교 (최대 5개)
- GET /floor-analysis?gu=&dong=&name= — 층별 가격 분석
- GET /seasonality — 계절 패턴
- GET /timing-signals — 매수 타이밍 시그널
- GET /leader-discount — 대장 대비 할인율
- GET /direct-trades — 직거래 비율 경고
- GET /dispersion?gu=&dong=&name= — 가격 분산도
- GET /classify?gu=&dong=&name= — 거래 신뢰도 분류
- GET /peak-gap — 고점 대비 현재가
- GET /market-cycle — 시장 사이클
- GET /alerts?type= — 이상 거래 (spikes, cancels, repeats)
- GET /insights?type= — 인사이트 (badges, champions, heat, build-age, deal-type)
- GET /trending?type= — 실시간 인기 (views, searches)

## 사용 예시
"강남구 래미안 아파트 평균 매매가": GET /trades?gu=강남구&name=래미안
"서울에서 가장 비싼 아파트": GET /top?n=10
"대치동 아파트 가격 추이": GET /trend?dong=대치동
"지금 매수 타이밍인 지역": GET /timing-signals

## 출처
국토교통부 실거래가 공개시스템 (rt.molit.go.kr)
데이터 제공: data.go.kr 공공데이터포털