아파트 단지 검색·평형별 시세
realty_search_complexesRead-onlyIdempotent
아파트 단지를 이름·지역으로 검색하고 평형별 실거래 시세를 함께 돌려준다. "○○아파트 34평 얼마야"류 단지 질문의 1차 도구다. query·region 중 하나는 필수.
**이 축의 자리(시세 도구 3종 중)**: 단지가 특정되면 **이게 기본**이다. 지역 평균
도구들(realty_region_price_stats·realty_area_price_bands)은 단지 간 편차를 뭉개므로
단지 질문에 쓰지 마라 — 같은 동 같은 평형에서 단지 평균이 24% 벌어진 실측이 있다.
반대로 지역 전체의 수준·추이 질문이면 저 둘로 가라.
prices_by_area가 평형별 시세다 — pyeong_exclusive(전용평)와 pyeong_supply_est(분양평
어림)를 병기하므로, 사용자가 말한 "34평"(보통 분양평)은 pyeong_supply_est로 맞춰 답하라.
단지 수준 avg_price는 전 평형이 섞인 평균이니 평수 질문에 쓰지 말 것.
층별(저층/고층/RR) 시세·프리미엄 질문은 realty_complex_pyeong_price로 —
거기 층 밴드별 집계(price_by_floor_band)가 있다(이 도구엔 층 축이 없다).
응답의 complex_key는 realty_complex_rent_by_pyeong·[유료] 단지 도구들에 그대로 넣는 키다.
**단지끼리 급을 견줄 때는 price_per_exclusive_m2(전용 ㎡당 실거래 단가)를 축으로 쓰라**
— 행마다 실리고, **sort='unit_price'로 그 순서대로 받을 수 있다**(백엔드에 없는 축이라
이 응답에 실린 행만 다시 세운 것이다 — sort_applied.scope 참조). 행의 scores
(composite·convenience)는 걸어서 닿는 **시설의 개수**이지 선호도가 아니다(직선거리만
세어 간선도로 횡단 같은 보행 장벽을 못 본다) — 그 점수로 단지에 줄을 세워 추천하지
마라. 입지 점수는 **미검증 참고값**이다(scores_meaning.status — transit 90점 이상 82%, 2026-10-17).
"역세권이야?"는 행의 nearest_station·subway_distance_m(직선 m)으로 답하라.
응답의 scores_meaning·unit_price_axis에 근거가 있다.
**견줄 때는 조건을 맞춰라 — 두 인자가 그 수단이다.** ㎡단가는 평형이 작을수록,
준공이 새로울수록 높다(⚠️ **전국 중앙값 이야기다** — 서울은 구축이 더 비싼 동이 28.0%다).
`area_band_m2=59`면 각 단지의 대표 단가가 **전용 59±3㎡ 행만으로** 다시 계산되고,
`construction_year_band=2018`이면 2013~2023년 준공 단지가 비교군으로 표시된다
(in_year_band). 연식이 더 지배적이다 — 법정동 안 ρ 중앙값이 연식 +0.7298 대
평형 +0.2245라, 연식이 섞인 ㎡단가 순위는 **사실상 신축 순**이 되기 쉽다. 두 인자 모두
**가격 계산·비교군 표시에만** 걸리고 단지 검색을 거르지 않는다(못 잰 단지는 목록에
남고 값이 null + 사유다). 몇 개를 쟀고 몇 개를 못 쟀는지는 응답의 coverage가 적는다.
**0.84.0부터 scores.composite는 school + convenience다**(transit을 뺐다 — 전국 실측에서
고유값의 86.8%가 90~100에 몰려 변별력이 없고, 합산에 넣으면 법정동 격자 ρ 중앙값이
0.0825→0.0654로 떨어졌다). 백엔드 원장의 옛 가중평균 값은 **composite_legacy로 병기**하니 이전 응답과
견줄 때 그쪽을 쓰라 — 두 값은 척도가 다르다(가중평균 대 단순합).
**세대수 조건은 min_households·max_households가 받는다**: "500세대 이상", "1,000세대 넘는 대단지", "300세대 이하 소규모"는
이 인자로 넣어라 — 종전엔 전달할 자리가 없어 그 질문이 통째로 실패했다. 행마다
households가 실린다. **households가 null인 단지는 세대수가 원장에 없는 것이지
작은 단지가 아니다** — 그래서 세대수 조건을 걸면 그 단지들은 크든 작든 제외되고,
몇 건이 그렇게 빠졌는지는 meta.households_scope가 적는다.
**'3억 이하 오래된 아파트'는 max_trade_price_10k·max_construction_year·sort='year_asc'가
받는다**: 예) region='노원구',
max_trade_price_10k=30000, max_construction_year=1996, sort='year_asc', period_months=12.
거래가 상한은 평균가가 아니라 **창 안 최저 실거래가**로 판정한다(행의 min_trade_price).
'재개발 호재'는 이 도구 축이 아니다 — 정비사업 구역은 realty_redevelopment(전체 표면).
단지 평판·거주 후기("살기 좋대?")는 원장에 없다 — 부르지 마라.
**거래 적은(환금성 낮은) 단지 확인 = sort='turnover_asc'** — 행마다 turnover_pct(창 안 매매
건수 ÷ 세대수 × 100, 창 그대로)와 turnover_pct_annualized(12개월 환산)가 실린다. 사실값이다 —
회전율이 낮다고 투자 부적격이라 판정하지 않는다. 세대수 미상이면 null + 사유(미상 ≠ 저회전).
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | 0부터 시작하는 페이지 번호 | |
| sort | No | name=이름순(거래량 많은 순), price=평균가 **높은** 순(전 평형 혼합 평균이라 큰 평형이 많은 단지가 앞에 온다), year=준공연도 **최신순(내림차순 — 신축이 먼저)**, **year_asc=준공연도 오래된 순(오름차순 — 구축이 먼저, 연도 미상은 맨 뒤)** — '오래된 아파트'·'재건축 연한 단지'를 찾을 때는 이것이다, **unit_price=전용 ㎡당 실거래 단가 높은 순** — 단지 간 급·선호를 견주는 축이다(못 잰 단지는 맨 뒤). ⚠️ unit_price는 백엔드에 없는 축이라 **이 응답에 실린 행만** 다시 세운 것이다 — total이 이 페이지보다 크면 '이 지역 ㎡단가 상위 N'으로 인용하지 마라(sort_applied.scope='page_only'가 그 사실을 값으로 싣는다). ⚠️ '오래된 단지'·'재건축 후보'에 sort='year'를 쓰면 정확히 반대 결과가 온다 — sort='year_asc'를 써라. 준공연도는 사업성(용적률·안전진단·구역 지정) 판정이 아니다(정비사업 축은 realty_reconstruction·realty_redevelopment). **turnover_asc=회전율(창 안 매매 건수 ÷ 세대수) 낮은 순** — '거래 적은 단지' 확인용이다. 백엔드 정렬이라 조건 전체가 대상이고 page로 이어진다. 세대수는 아는데 창 안 거래가 안 잡힌 단지, 세대수 미상 단지는 잰 단지 **뒤**에 온다(0%·저회전이 아니다 — sort_applied.turnover_scope가 각 건수를 싣는다) | name |
| limit | No | 단지 수 — 평형별 시세가 포함돼 응답이 무겁다. 최대 20이고 더 받으려면 limit을 올리지 말고 **page를 넘겨** 이어 받아라(응답의 total이 전체 건수다 — 다만 서버가 지역 토큰을 뒤에서 검증한 경로에서는 total이 null이고 meta.total_unavailable이 사유를 적는다. 그리고 **sort='unit_price'로 받은 응답이 잘렸으면 page로 이어받을 수 없다** — sort_applied.page_continuation이 그 사실을 값으로 싣는다). 요청분을 다 실으면 응답이 크기 상한을 넘는 경우 **실제 반환 수를 줄이고 meta.size_capped**에 총계·이어받는 호출을 값으로 싣는다 — 조용히 자르지 않는다 (허용 범위 1~20) | |
| query | No | 단지명 일부 (예: 래미안, 마포래미안푸르지오) | |
| region | No | 시군구명 (예: 마포구, 서울특별시 마포구). **법정동까지 넣어도 된다**(예: '강남구 대치동') — 백엔드는 동으로 거르고 나머지 토큰은 서버가 검증해 note에 적는다 | |
| area_band_m2 | No | **평형을 고정해 단지끼리 견줄 때** 넣는다(전용면적 ㎡ — 분양면적이 아니다). 예: '59㎡대로 맞춰서 비교' → 59. 전용 ±3.0㎡ 근사 매칭이고(원장 면적이 59.224·59.9처럼 단지마다 달라 정확 일치는 대부분 0건이다), 각 단지의 price_per_exclusive_m2가 **그 밴드 안 평형 행만으로 다시 계산된다**. ⚠️ 이 인자는 **가격 계산에만** 걸리고 단지 검색을 거르지 않는다 — 밴드에 거래가 없는 단지도 목록에 그대로 실리고 그 값은 null + 사유다. 밴드에 든 행에는 in_area_band=true가 붙는다 (허용 범위 0 초과~500) | |
| period_months | No | 가격 집계 기간(개월). 비우면 2024-01 이후 전체 (허용 범위 1~24) | |
| max_households | No | 세대수 상한 — '300세대 이하 소규모'처럼 위쪽을 자를 때. min_households와 함께 주면 구간이 된다 | |
| min_households | No | **세대수 하한** — '500세대 이상', '대단지'를 여기에 넣는다(예: 500). 세대수가 원장에 없는 단지는 이 조건에서 제외되고 그 건수를 meta.households_scope로 실토한다(미상 ≠ 소규모) | |
| include_footnotes | No | true면 계산값 근거 전문(산식·모집단·기간·원천)을 footnotes에 싣는다. 기본은 행마다 한 줄 요지 | |
| max_trade_price_10k | No | **거래가 상한(만원)** — '3억 이하로 살 수 있는 단지'는 30000. 집계 창 안에 이 금액 **이하 실거래가 1건 이상** 있었던 단지만 남긴다(평균가가 아니다 — 소형 평형만 3억대인 단지도 잡힌다; 행의 min_trade_price가 그 최저 거래가). **이 인자는 검색을 거른다.** 창 안 거래가 없는 단지는 판정 불가라 빠지고 그 건수를 meta.price_year_scope에 싣는다. '지금 3억 매물'이 아니라 '창 안에 3억 이하로 팔린 적이 있다'다 — 호가·매물은 없다. 최근 시세로 보려면 period_months=12를 함께 줘라 | |
| max_construction_year | No | **준공연도 상한** — '오래된 아파트'·'30년 넘은 단지'를 거를 때(예: 준공 30년 이상 = 올해-30). **이 인자는 검색을 거른다**(construction_year_band는 표시만 한다). 준공연도가 원장에 없는 단지는 판정 불가라 빠지고 그 건수를 meta.price_year_scope에 싣는다. 연한은 재건축 **자격의 하나**일 뿐 사업성·구역 지정·'호재'가 아니다 (허용 범위 1900~2100) | |
| construction_year_band | No | **연식을 맞춰 단지끼리 견줄 때** 넣는 기준 준공연도. 예: 2018 → 2013~2023년 준공(±5년, 폭 10년)이 비교군이 된다. **연식은 ㎡단가를 가장 강하게 끄는 축이다** — 법정동 안에서 준공연도와 ㎡단가의 순위상관 ρ 중앙값이 +0.7298로 평형(+0.2245)·입지점수(+0.0707)보다 지배적이라, 연식이 섞인 비교는 사실상 '신축 순'이 되기 쉽다(⚠️ 방향은 지역마다 반대일 수 있다 — **서울은 ρ +0.3833이고 구축이 더 비싼 동이 28.0%, 세종은 36.8%**다. 재건축 기대가 가격에 들어간 U자 구간이다). ⚠️ 이 인자도 검색을 거르지 않는다 — 밴드 밖 단지는 목록에 남고 행마다 in_year_band로 갈라 적힌다(준공연도가 원장에 없으면 null: **판정 불가이지 구식이 아니다**). area_band_m2와 함께 주면 둘 다 걸린다 (허용 범위 1900~2100) |