| name | daangn-realty-search |
| description | 당근부동산(realty.daangn.com) 공개 웹 데이터로 지역 기반 부동산 매물 검색과 상세 확인을 수행한다. 문의/예약/계약 자동화는 제외한다. |
| license | MIT |
| metadata | {"category":"real-estate","locale":"ko-KR","phase":"v1.5"} |
Daangn Realty Search
What this skill does
당근부동산 지도 페이지(realty.daangn.com/map/{name1}/{name2}/{name3})의 SSR window.RELAY_STORE(Relay 정규화 스토어)를 파싱해 매물 후보를 정리한다. 제목·주소·층수는 상세 페이지의 JSON-LD에서 보강한다. 외부 패키지 없이 Python 표준 라이브러리만 사용한다.
When to use
- "당근부동산 매교동 월세 찾아봐"
- "수원 팔달구 상가 매물 봐줘" (
--expand로 인접 동까지)
- "이 당근부동산 URL 상세 요약해줘"
When not to use
- 당근 계정 로그인이 필요한 작업
- 채팅, 찜, 거래 제안, 문의, 예약, 계약, 구매처럼 상대방/계정에 영향을 주는 작업
- CAPTCHA/봇 차단/로그인벽 우회가 필요한 작업
Prerequisites
Data surfaces (2026-06 도메인 이전 대응)
- Region resolver:
https://www.daangn.com/kr/api/v1/regions/keyword?keyword=<지역명> → {"locations":[{id,name1,name2,name3,name*Id,depth}]}
- 매물 목록:
https://realty.daangn.com/map/{name1}/{name2}/{name3} 의 window.RELAY_STORE
- 상세:
https://realty.daangn.com/articles/<id> 의 application/ld+json
⚠️ 구버전(www.daangn.com/kr/realty/?_data=routes/kr.realty._index)은 2026-06부터 HTTP 204(빈 응답)로 폐기됨. 절대 사용 금지.
RELAY_STORE 파싱 경로 (검증됨)
ArticleFeedConnection.edges → ArticleFeedEdge.node → ArticleFeedCard.article → Article
- 스토어에
ArticleFeedCard가 직접 다 들어있어, Card를 순회 → article ref 디레퍼런스가 가장 견고하다.
Article: originalId, area(㎡, 문자열일 수 있어 float 변환 필수), salesTypeV3(→*SalesTypeV2.type), trades(→ Month/Buy/BorrowTrade)- 가격 단위 = 만원:
deposit(보증금), monthlyPay(월세), price(매매가). 예: deposit 2000 = 2천만원, price 28700 = 2억8,700만.
window.RELAY_STORE는 JS 문자열로 이스케이프돼 있다 → json.loads(json.loads('"'+raw+'"')) 2단 디코드.
Trade 유형 & 평당 단가
| 거래유형 | typename | 가격 필드 | 평당 단가 |
|---|
| 월세(MONTH) | MonthTrade | deposit + monthlyPay | monthlyPay / 평 |
| 매매(BUY) | BuyTrade | price | price / 평 |
| 전세(BORROW) | BorrowTrade | deposit | deposit / 평 |
평 = ㎡ / 3.305785.
salesType enum
APART, OFFICETEL, STORE, OPEN_ONE_ROOM, SPLIT_ONE_ROOM, TWO_ROOM, HOUSE 등.
층수 (상세 JSON-LD)
목록엔 층수가 없다. 상세 페이지 Product.additionalProperty 배열에서:
floor(예 "8.0") / topFloor(예 "10") → floor_label = "8층/10층"nearbySubwayStation 도 함께 추출.
제목은 Product.name, 주소는 Place.name.
Commands
python3 daangn-realty-search/scripts/daangn_realty.py search --region "매교동" --limit 20
python3 ... search --region "매교동" --trade-type BUY
python3 ... search --region "매교동" --sales-type STORE,OFFICETEL
python3 ... search --region "매교동" --expand --expand-max 6
python3 ... search --region "매교동" --titles 0
python3 ... detail "https://realty.daangn.com/articles/2947028"
옵션: --limit(기본 20), --titles N(상세로 제목·층수 보강할 상위 N, 기본 5, 0=끔), --expand/--expand-max(기본 6).
기존 CLI 호환 옵션인 --keyword는 반환 매물의 공개 필드 텍스트를 필터링한다. --only-verified는 공개 피드에서 별도 인증 필드를 제공하지 않아 호환 목적으로만 허용한다.
Output fields
매물: article_id, salesType, area_sqm, area_pyeong, trades[{type,label,deposit_manwon,monthly_manwon,price_manwon,per_pyeong_manwon}], url, region, title, address, floor_label, nearby_subway, release_date
release_date는 상세 페이지 JSON-LD의 Product.releaseDate(ISO 8601, UTC)이며 --titles 보강 대상 매물에만 채워진다. 최초 등록일인지 최근 끌어올리기/수정일인지는 당근 쪽 명세에 없어 확정할 수 없다.
Region handling
지역명 → region API로 내부 id 해석. 동명이 여럿이면 정확일치 → 서울 depth=3 → 첫 후보 순. 응답에 effective_region 포함. --expand는 같은 name2Id(구/시) 인접 동을 모은다.
Safety and scope
- 읽기 전용 검색/상세만. 로그인·채팅·거래·예약·계약 자동화 없음.
- 공개 표면이 바뀌거나 빈 응답/봇 차단이면 실패 모드로 보고하고 우회하지 않는다.
- 결과는 실시간 호가라 실거래와 다를 수 있으므로 source URL을 함께 제시.
Failure modes
RELAY_STORE 없음 (sources note) → 페이지 구조 재변경 또는 봇 차단. HTML 구조 재확인 필요.- 시군구(name2) 랜딩 URL은 매물이 없다 — 반드시 동(name3)까지 있어야 articleFeed가 SSR로 채워진다.
- 동명이 넓거나 중복되면 다른 행정동 선택 가능.
- 상세는 삭제/비공개 글에서 실패할 수 있다.
Done when
- 지역 id 해석 → map URL의 RELAY_STORE에서 매물 추출 → source URL·effective_region 포함.
- 인증/거래성 액션은 수행하지 않았다.
Notes
- Windows stdout 한글 깨짐 방지: 지원 런타임에서는
sys.stdout.reconfigure(encoding='utf-8')를 적용한다.
area·가격 필드가 문자열로 오는 케이스가 있어 모든 수치 연산 전 float 변환 가드.
