부동산 실거래가 사용 가이드
국토교통부 공공데이터 API로 아파트·오피스텔의 매매·전월세 실거래 기록을 조회하는 스킬입니다. Claude에게 말로 부탁하면 됩니다 — “강남구 아파트 2026년 1월 실거래가 알려줘”, “분당 전세 시세 확인해줘”처럼요. 지역 코드나 API 파라미터를 직접 다룰 필요는 없습니다.
사전 준비
공공데이터포털 API 키가 필요합니다.
- https://www.data.go.kr 회원가입
- 사용하려는 데이터셋을 각각 활용신청 (전부 자동승인, 신청 즉시 5~30분 내 사용 가능)
- 마이페이지에서 Decoding 키(일반 인증키) 복사
- 발급받은 키를 Claude Desktop 지침에 추가합니다 — Claude Desktop → 설정 → 일반 → “Claude 지침” 에 아래 한 줄을 붙여넣고 저장하세요.
KO_DATA_API_KEY=발급받은_키자세한 가입·키 발급 절차(Decoding 키 주의사항 포함)는 공공데이터포털 발급 가이드를 참고하세요.
한 번 넣으면 이후 모든 대화에서 Claude가 자동으로 사용합니다 — .env 같은 파일을 직접 만들 필요가 없습니다.
개발자라면 작업 폴더 루트의
.env에 같은 한 줄을 넣어도 됩니다.
동일 인증키 하나로 4개 데이터셋 모두 호출 가능하지만, 데이터셋마다 별도 활용신청이 필요합니다. 신청하지 않은 서비스를 조회하면 오류 메시지에 해당 신청 링크가 자동으로 표시됩니다.
자주 쓰는 요청
| 하고 싶은 것 | 이렇게 말하세요 |
|---|---|
| 아파트 매매 실거래 조회 | ”강남구 아파트 2026년 1월 실거래가 알려줘” |
| 요약 통계(평균·중위·최고가) | “강남구 아파트 2026년 1월 실거래가 평균이랑 중위가 알려줘” |
| 전월세 시세 | ”성남시 분당구 2026년 1월 전월세 시세 확인해줘” |
| 특정 단지만 | ”강남구에서 래미안 단지 매매가만 보여줘” |
| 지역명 확인 (API 키 불필요) | “국토부 지역코드에서 강남 들어간 지역 다 보여줘” |
| 오피스텔 실거래 | ”강남구 오피스텔 2026년 1월 매매 실거래 조회해줘” |
출력 형식
| 형식 | 설명 | 사용 시점 |
|---|---|---|
| JSON (기본) | 구조화된 JSON 배열 | 다른 스킬과 연계하거나 후속 가공할 때 |
| 테이블 | 정렬된 표 | 수치를 눈으로 바로 읽고 비교할 때 |
| 요약 통계 포함 | 평균·중위·최고가 통계 추가 | 시세 흐름을 한눈에 파악할 때 |
출력 형식을 바꾸고 싶으면 “표로 보여줘”, “요약 통계도 포함해줘”처럼 말하면 됩니다.
팁
- 지역명이 정확하지 않으면 먼저 확인: 시·구 명칭이 살짝만 달라도 “지역 코드를 찾을 수 없습니다” 오류가 납니다. “국토부 지역코드에서 강남 들어간 지역 보여줘”처럼 확인한 뒤 요청하세요.
- 요약 통계로 한눈에 파악: 거래 수백 건을 직접 보지 말고 평균·중위·최고가 통계로 시세 흐름부터 잡으세요.
- 단지명 일부로도 필터링 가능: “래미안”처럼 단지명 일부만 말해도 해당 단지 거래만 필터링됩니다. 한 단지를 시계열로 추적할 때 유용합니다.
- 지역 코드 확인은 API 키 없이도 가능: 지역명 목록을 미리 확인할 때는 API 키 없이도 동작합니다.
제한사항
- 아파트·오피스텔 실거래만 지원: 단독·다세대·상가 등 다른 주택 유형은 조회되지 않습니다.
- 신고 지연으로 1~2개월 데이터 누락 가능: 실거래 신고 의무 기한 때문에 조회 월 대비 최근 1~2개월 데이터는 일부 누락될 수 있습니다.
- 월 단위 조회만 가능: 년월(YYYYMM) 형식만 허용됩니다. 일별·주별 조회나 다중 월 일괄 조회는 지원하지 않습니다. 연간 조회가 필요하면 월별로 나누어 여러 번 요청하세요.
- 공공데이터포털 트래픽 한도: 일일 호출량 한도가 있으므로 동일 조건을 반복 조회하지 마세요.
- 실거래가만 제공: 호가·시세·의도 가격은 포함되지 않습니다. 국토교통부에 신고된 실제 거래 가격만 반환됩니다.
안 될 때
증상 (오류 코드) | 원인 / 해결 |
|---|---|
| ”API 키가 설정되지 않았습니다” | Claude 지침(또는 .env)에 KO_DATA_API_KEY=키 누락. 위 “사전 준비” 확인 |
| ”지역 코드를 찾을 수 없습니다” | 지역명 불일치. “국토부 지역코드 보여줘”로 정확한 명칭 확인 |
| ”HTTP 403 Forbidden — 게이트웨이 권한 거부” | 해당 데이터셋 활용신청 미완료 또는 동기화 지연. 오류에 표시된 신청 링크에서 신청 후 5~30분 대기 |
”데이터가 없습니다” (resultCode=03) | 해당 기간에 거래 없음 또는 신고 지연. 다른 년월로 재시도 |
”활용 미승인” (resultCode=20) | 마이페이지에서 활용신청 승인 상태 확인 |
”등록되지 않은 서비스키” (resultCode=30) | 마이페이지에서 Decoding 키 다시 복사해 Claude 지침(또는 .env) 갱신 |