realty-deals 사용 가이드

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

---

처음 설정하기

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

1. data.go.kr에 가입합니다.
2. 원하는 실거래가 서비스를 개별 활용신청합니다.
   • 아파트 매매: https://www.data.go.kr/data/15126469/openapi.do
   • 아파트 전월세: https://www.data.go.kr/data/15126474/openapi.do
   • (오피스텔·연립다세대·토지 등도 동일하게 유형별로 신청)
3. 발급받은 API 키를 .env 파일에 넣습니다 (권장) — 작업 폴더(Cowork 연결 폴더 / Claude Code 프로젝트 루트)(연결한 폴더가 여러 개면 아무 폴더나) 루트에 .env 파일을 만들고 아래 한 줄을 넣어 두면 스킬이 자동으로 찾아 읽습니다. 점(.)으로 시작하는 파일을 만들기 어렵다면 환경변수.txt 라는 이름으로 만들어도 똑같이 읽힙니다(메모장이 .txt 를 붙여 .env.txt 가 되어도 됩니다).

KO_DATA_API_KEY=발급받은_키

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

Claude Desktop의 "Claude 지침"(설정 → 일반)에 같은 내용을 적는 방식도 동작하지만, 대화 컨텍스트에 값이 노출되므로 .env 파일을 권장합니다.

개발자라면 셸 환경변수로 넣어도 됩니다.

자동승인이라도 동기화에 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월까지"처럼 기간 범위를 말하면 달별로 자동으로 순회하며 수집합니다.
• 이전 스킬 사용자: 기존 itda-gov/skills/realestate를 쓰던 분은 KO_DATA_API_KEY를 그대로 사용하면 됩니다. 기존 4유형(아파트 매매·전월세, 오피스텔 매매·전월세)은 동일하게 동작합니다.

---

안 될 때

증상	원인 / 해결
"API 키가 없다"는 안내 (config)	.env 파일(또는 Claude 지침)에 KO_DATA_API_KEY가 없거나 비어 있음. 위 "처음 설정하기" 확인
"지역을 모르겠다"는 안내 (args)	지역명을 다시 말하거나 /realty-deals 지원하는 지역 목록 알려줘로 확인
권한 오류 (api, 코드 20/30)	활용신청 직후 동기화 대기 중. 5~30분 후 다시 요청
API 서비스 오류 (api)	공공데이터포털 활용신청 승인 상태를 확인하고 다시 요청