스킬.잇다
공공데이터 스킬팩

realty-deals

국토부 부동산 실거래 12개 유형을 단일 인터페이스로 수집 (다개월·CSV/JSON)

v0.13.2 realestate molit trade rent

realty-deals 사용 가이드

국토교통부 부동산 실거래가 12개 유형(아파트·오피스텔·연립다세대·단독다가구·토지·상업업무용·공장창고·분양입주권의 매매/전월세)을 한 번에 수집합니다. /realty-deals 강남구 2026년 1~6월 아파트 매매 실거래 모아줘, /realty-deals 분당 연립다세대 매매 2025년 데이터 CSV로 줘처럼 말하면 됩니다.


처음 설정하기

이 스킬은 공공데이터포털 API 키가 필요합니다. 조회할 거래 유형별로 개별 활용신청을 해야 합니다.

  1. data.go.kr에 가입합니다.
  2. 원하는 실거래가 서비스를 개별 활용신청합니다.
  3. 발급받은 키를 itda-hyve 앱의 “시크릿” 탭에 KO_DATA_API_KEY 라는 이름으로 등록합니다(itda-hyve 0.10.4 이상이 없으면 여기서 내려받아 설치하고 Claude Desktop 에 연결합니다). 키 값은 그 앱 안에만 저장되고 Claude 에게는 전달되지 않습니다(Claude 는 이름만 씁니다).

공공데이터포털은 같은 키를 Encoding / Decoding 두 형태로 보여 줍니다. Decoding 키를 등록하세요 — Encoding 키를 넣으면 “등록되지 않은 서비스키”(resultCode 30) 오류가 납니다.

자세한 가입·키 발급 절차(Decoding 키 주의사항 포함)는 공공데이터포털 발급 가이드를 참고하세요.

키 값을 Claude 대화창에 붙여 넣지 마세요 — Claude 는 그 값을 쓰지 않습니다.

자동승인이라도 동기화에 5~30분이 걸릴 수 있습니다. 신청 직후 오류가 나면 잠시 기다렸다가 다시 요청하세요.


지원하는 거래 유형

유형 매매 전월세
아파트 ✅ ✅
오피스텔 ✅ ✅
연립다세대 ✅ ✅
단독다가구 ✅ ✅
토지 ✅ —
상업업무용 ✅ —
공장창고 ✅ —
분양입주권 ✅ —

자주 쓰는 요청

하고 싶은 것 이렇게 말하세요
아파트 매매 실거래 조회 /realty-deals 강남구 2026년 1월 아파트 매매 실거래 보여줘
여러 달 한 번에 수집 /realty-deals 성남시 분당구 2026년 1~6월 아파트 매매 전체 모아줘
전월세 조회 /realty-deals 마포구 2026년 1~6월 아파트 전월세 조회해줘
아파트 외 유형 /realty-deals 강서구 오피스텔 전월세 2026년 상반기 조회해줘
요약 통계 포함 /realty-deals 강남구 2026년 1~6월 아파트 매매 실거래 모아줘, 평균·중위·최대·최솟값도 같이 보여줘
특정 단지만 /realty-deals 래미안퍼스티지 거래 내역만 뽑아줘
지역코드 확인 /realty-deals 지원하는 지역 코드 목록 알려줘
CSV로 저장 /realty-deals 강남구 2026년 1월 아파트 매매 실거래 CSV로 저장해줘

알아두면 좋은 점

  • 전량 수집: 구(舊) 스킬은 첫 페이지만 가져오는 버그가 있었습니다. 이 스킬은 국토교통부 API의 전체 건수(totalCount)를 기준으로 모든 페이지를 끝까지 수집합니다.
  • 다월 범위 자동 처리: “1월부터 6월까지”처럼 기간 범위를 말하면 달별로 자동으로 순회하며 수집합니다. 먼저 예상 요청 수를 알려 드립니다.
  • 다 받은 뒤에만 결과를 냅니다: 빠진 쪽이 있으면 Claude 가 마저 받은 뒤 결과를 냅니다. 받는 사이 거래가 늘어 목록이 바뀐 달은 처음부터 다시 받아야 하는데, 이미 받은 파일을 덮어쓰게 되므로 Claude 가 먼저 물어봅니다.
  • 해제된 거래: 계약 뒤 해제 신고된 매매도 원본 목록에는 “해제” 표시와 함께 그대로 나옵니다. 평균·중위 같은 요약 통계에서는 기본으로 빼고 몇 건을 뺐는지 알려 드립니다. 넣고 싶으면 “해제 거래도 포함해줘”라고 말하세요.
  • 이전 스킬 사용자: 키 이름 KO_DATA_API_KEY 는 그대로이고, 등록 위치만 itda-hyve 시크릿 탭으로 바뀌었습니다. 기존 4유형(아파트 매매·전월세, 오피스텔 매매·전월세)은 동일하게 동작합니다.

안 될 때

증상 원인 / 해결
“키가 등록되지 않았다”는 안내 (secret_missing) itda-hyve 시크릿 탭에 KO_DATA_API_KEY 가 없음. 위 “처음 설정하기” 확인
“지역을 모르겠다”는 안내 (args) 지역명을 다시 말하거나 /realty-deals 지원하는 지역 목록 알려줘로 확인
권한 오류 (api, 코드 20/30) 활용신청 직후 동기화 대기 중. 5~30분 후 다시 요청
API 서비스 오류 (api) 공공데이터포털 활용신청 승인 상태를 확인하고 다시 요청