주소 문자열을 구/동/번지 + 법정 코드로 해석하고 필지 구성(부속지번)을 확인한다.

예: '구로구 구로동 1128-1', '서울 성수동2가 321-90' (동만 줘도 구를 역추적). 다른 도구를 쓰기 전 주소가 모호할 때 먼저 호출. lot_structure='조회실패'는 '단일 필지'가 아니라 미확인이다 — 구분해 읽을 것.

지번의 실거래 종합카드 1콜 — 최신 매매가·평단가·매도/매수·매칭 신뢰도 + 표제부.

서울 상업업무용 매매 한정. months(160)는 조회 기간(개월). 첫 조회는 표제부·실거래 API를 불러 수십 초수 분 걸릴 수 있다(이후 15분 캐시). 수치를 계산에 쓸 때는 텍스트가 아니라 structuredContent 를 읽을 것 (status='OK' 일 때만 latest 에 실측값이 있다).

지번의 매칭 실거래 이력 전체(최신순) — 각 건에 매칭 신뢰도 표기.

서울 상업업무용 매매 한정. months(1~60) 기본 24개월. 재거래·가격 추이를 계산할 때는 텍스트가 아니라 structuredContent 의 transactions[] 를 읽을 것 (건별 신뢰도가 다를 수 있다).

최신 매칭의 근거를 투명하게 — 표제부 앵커값 vs 거래행값, 발화 단계, 필지세트.

추정매칭 검증·감사용. 보고서 인용 전 반드시 확인 권장. structuredContent 의 comparison 이 앵커 대 거래행 대조(delta·equal)를 담는다.

구·동 단위 상업업무용(통건물) 시세 — 동이면 후보 거래까지, 구면 통계·동별 순위.

area 에 구만 주면('강남구') 구 모드, 동을 주면('대치동') 동 모드다. 지번을 몰라도 '동 + 가격대'로 조회한다. 예: area='성수동1가', min_eok_per_pyeong=4.5, max_eok_per_pyeong=5.5 → 연면적 평당 4.5~5.5억 거래를 최신순으로. min/max 가 0 이면 해당 방향 제한 없음. 평당가 기준 = 연면적(거래금액÷연면적평). road_contains(예: '연무장길')를 주면 표제부 역매칭으로 도로명이 특정된 거래만 부분일치 필터 — 도로명 미상(마스킹 미복원) 거래는 제외되며 그 건수를 함께 고지한다. 서울 상업업무용 매매 한정(v1). 첫 조회는 표제부 API 로딩으로 수십 초 걸릴 수 있다. 표본 대표성을 판단할 때는 structuredContent 의 coverage(모수 분해)를 함께 읽을 것.

취급 범위는 통건물(유형='일반')뿐 — 집합(구분상가)은 제외한다(coverage.jiphap_excluded 에 건수). 그러므로 stats 는 전부 '통건물 시세'이며, 상가 한 칸 시세가 아니다.

area 에 구만 주면('강남구'·'강남') 구 모드로 동작한다 — 구 전체 시세와 분기 추이, 그리고 by_dong(동별 대지 평단가 내림차순)을 낸다. 구 모드는 표제부 역매칭을 돌리지 않아 deals 가 항상 비어 있다(scope='구' 로 구분). 개별 지번·거래가 필요하면 동으로 다시 부를 것.

동 평균 평단가는 stats(연면적·대지)에 담긴다 — 가격대·도로명 필터와 무관하게, 표제부 역매칭 이전의 국토부 원본 실거래(통건물, 해제·산출불가 제외)로 산출하므로 전수에 가깝다. '이 동 평단가 시세'를 물으면 deals 가 아니라 stats 를 근거로 답할 것 (deals 는 필터 통과분이라 평균 내면 편향된다). 평균이 필요할 뿐이면 min/max 를 주지 말고(밴드 없이) 호출하면 된다.

지번 하나로 실거래 데이터카드 PNG 1장(4:5)을 만든다 — 조회부터 이미지까지.

카드에 들어가는 값은 전부 실거래·건축물대장 실측값이다(매매가·토지/연면적· 평단가·용도지역·준공연도·거래일·매도매수). 홍보 문구는 넣지 않는다.

매칭 신뢰도가 카드에 배지로 찍힌다. 이미지가 손을 떠난 뒤에는 대화로 고지할 수 없기 때문이며, '추정매칭' 이하는 색으로 구분된다. 고객에게 내밀기 전에 match_explain 으로 근거를 확인시키는 걸 권한다.

사진이 없으면 렌더하지 않고 PHOTO_MISSING 으로 멈춘다 — 카드는 건물 사진 위에 수치를 얹는 형태라, 사진이 없으면 회색 판이 나가고 결국 다시 만들게 된다. 이때는 재시도하지 말고 사용자에게 사진 경로를 물어볼 것. 사진 없이 진행하기로 사용자가 정하면 allow_no_photo=true 로 재호출한다. eyebrow 로 매매가 위 골드 한 줄을 덮어쓸 수 있다. 기본값은 '<구> 실거래 · YYYY.MM'. '최고가/최저가' 같은 단정 표현은 쓰지 말 것 — 이 도구의 조회 범위(서울 상업업무용·기간 한정) 안에서의 순위일 뿐이라 카드에 박히면 근거 없는 단정이 된다. 저장 위치는 ~/deal-locator-cards/<날짜>/ (DEAL_LOCATOR_CARD_DIR 로 변경 가능).

최초 1회 playwright install chromium 이 필요하다.