realty-price-stats 사용 가이드
한국부동산원 R-ONE 가격지수·전월세전환율과 실거래 데이터 기반 파생 통계(평균·중위·최대·최솟값)를 제공합니다.
/realty-price-stats 강남구 아파트 주간 가격지수 6개월치 가져와줘, /realty-price-stats 분당구 최근 3개월 평균·중위 매매가 통계 보여줘처럼 말하면 됩니다.
처음 설정하기
키는 두 가지이고, 둘 다 itda-hyve 앱의 “시크릿” 탭에 이름을 맞춰 등록합니다. itda-hyve 0.10.4 이상이 없으면 여기서 내려받아 설치하고 Claude Desktop 에 연결합니다. 키 값은 그 앱 안에만 저장되고 Claude 에게는 전달되지 않습니다. Claude Code 와 Cowork 모두 같은 방법입니다. .env 같은 파일에 적어 두는 방식은 쓰지 않습니다 — 스킬이 그 파일을 읽지 않습니다.
R-ONE 가격지수 조회
한국부동산원 R-ONE 인증키가 필요합니다.
- R-ONE 부동산통계정보에 회원가입하고 로그인합니다.
- 메뉴 Open API 에서 인증키를 신청해 받습니다(받은 키는 「인증키 발급내역」에서 다시 볼 수 있습니다).
- 받은 키를 itda-hyve 시크릿 탭에
RONE_API_KEY라는 이름으로 등록합니다.
키 값을 대화창에 붙여 넣지 마세요. 붙여 넣어도 Claude 는 그 값을 쓰지 않고 시크릿 탭 등록을 안내합니다.
실거래 파생 통계 추가 조회
실거래 데이터 기반 파생 통계(평균·중위·최대·최솟값)를 보려면 공공데이터포털 키가 필요합니다.
- data.go.kr에서 조회할 실거래 서비스(예: 아파트 매매 https://www.data.go.kr/data/15126469/openapi.do)를 활용신청합니다.
- 발급받은 키를 itda-hyve 시크릿 탭에
KO_DATA_API_KEY라는 이름으로 등록합니다.realty-deals스킬을 이미 쓰고 있다면 이미 등록돼 있습니다.
공공데이터포털은 같은 키를 Encoding / Decoding 두 형태로 보여 줍니다. Decoding 키를 등록하세요 — Encoding 키를 넣으면 “등록되지 않은 서비스키”(resultCode 30) 오류가 납니다. 자세한 절차는 공공데이터포털 발급 가이드를 참고하세요.
KB 데이터허브는 공식 API가 없어 스크래핑하지 않습니다. KB 데이터가 필요하면 공식 다운로드 페이지(https://data.kbland.kr)에서 직접 파일을 받아 활용하세요.
지원하는 지수 유형
| 유형 | 설명 |
|---|---|
| 주간 가격지수 | 아파트 매매가격의 단기 흐름 추적 (한국부동산원 주간아파트동향, 주 단위) |
| 월간 가격지수 | 아파트 매매가격의 중장기 추세 파악 (월간동향, 월 단위) |
| 전월세전환율 | 아파트 전세를 월세로 바꿀 때 적용되는 비율(%) 추이 |
지수는 전국·시도·권역·시군구 행이 한꺼번에 옵니다. “서울만”, “강남구만”처럼 말하면 그 지역 행만 보여 드립니다.
자주 쓰는 요청
| 하고 싶은 것 | 이렇게 말하세요 |
|---|---|
| 주간 가격지수 조회 | /realty-price-stats 2026년 1~6월 아파트 주간 가격지수 가져와줘 |
| 지역을 좁혀 조회 | /realty-price-stats 2026년 상반기 서울 아파트 월간 가격지수만 보여줘 |
| 월간 가격지수 조회 | /realty-price-stats 2026년 상반기 아파트 월간 가격지수 보여줘 |
| 전월세전환율 추이 | /realty-price-stats 2026년 1~6월 전월세전환율 추이 조회해줘 |
| 실거래 파생 통계 | /realty-price-stats 강남구 2026년 1월 아파트 매매 평균·중위·최댓값 통계 보여줘 |
| 단지별 통계 비교 | /realty-price-stats 강남구 2026년 상반기 아파트 매매를 단지별로 묶어서 통계 보여줘 |
알아두면 좋은 점
- 두 가지 데이터 출처: R-ONE 지수(한국부동산원 공식 시계열)와 실거래 파생 통계(공공데이터포털 raw 데이터 기반)는 목적이 다릅니다. 시장 흐름 추적에는 R-ONE 지수가, 특정 지역·기간의 시세 분포 파악에는 파생 통계가 유용합니다.
- R-ONE 지수도 다 받은 뒤에만 냅니다: 한 번에 1,000행씩 받습니다. 기간이 길면(예: 월간 지수 5년치 약 1만 4천 행) 먼저 예상 요청 수를 알려 드리고, 상한(2만 행)을 넘을 것 같으면 받기 전에 기간을 좁힐지 여쭙니다.
- 실거래 통계는 다 받은 뒤에만 냅니다: 한 달의 거래를 100건씩 나눠 받습니다. 빠진 쪽이 있으면 평균·중위가 틀리므로, Claude 가 마저 받은 뒤 계산합니다. 기간이 길면 먼저 예상 요청 수를 알려 드립니다.
- 해제된 거래는 통계에서 뺍니다: 계약 뒤 해제 신고된 매매는 실제 시세가 아니므로 평균·중위에서 기본으로 빼고, 몇 건을 뺐는지 알려 드립니다. 넣고 싶으면 “해제 거래도 포함해줘”라고 말하세요.
- 단지별 비교: 실거래 파생 통계를 단지명 기준으로 묶어달라고 하면 단지별로 평균·중위·최대·최솟값을 비교할 수 있습니다.
- KB 데이터: KB 데이터허브는 공식 API를 제공하지 않아 이 스킬에서 직접 조회할 수 없습니다. 필요 시 https://data.kbland.kr에서 직접 파일을 다운로드하세요.
안 될 때
| 증상 | 원인 / 해결 |
|---|---|
“키가 등록되지 않았다”는 안내 (secret_missing) |
itda-hyve 시크릿 탭에 RONE_API_KEY(가격지수) 또는 KO_DATA_API_KEY(실거래 통계)가 없음. 위 “처음 설정하기” 확인 |
R-ONE “인증키가 유효하지 않다” (api, ERROR-290) |
시크릿 탭의 RONE_API_KEY 가 틀렸거나 앞뒤에 공백이 붙음. R-ONE Open API 「인증키 발급내역」에서 다시 복사해 등록 |
R-ONE “오늘 호출 한도를 넘었다” (api, ERROR-337) |
일별 트래픽 제한. 내일 다시 요청 |
“받은 쪽이 모자라다” (incomplete) |
기간이 길어 여러 번 받아야 함. Claude 가 남은 요청 수를 알려 드리고 이어 받습니다 |
받은 응답이 5행뿐이라 멈춤 (input) |
인증키 없이 받은 견본 응답. 시크릿 탭에 RONE_API_KEY 를 등록한 뒤 다시 요청 |
공공데이터 “등록되지 않은 서비스키” (api, 코드 30) |
Encoding 키를 등록했을 가능성. 시크릿 탭에 Decoding 키로 다시 등록 |
API 서비스 오류 (api) |
각 포털 활용신청 승인 상태를 확인하고 다시 요청 |