---
title: "realty-deals"
description: "국토교통부 부동산 실거래 12개 유형을 단일 인터페이스로 수집하는 스킬입니다. \"최근 6개월 강남구 아파트 실거래 전부 받아줘\", \"분당 연립다세대 매매 2025년 데이터 CSV로 줘\", \"강서구 오피스텔 전월세 조회해줘\"처럼 말하면 됩니다. 전체 페이지네이션·다개월 범위·CSV/JSON 출력을 지원합니다. [책임 경계] 본 스킬은 국토교통부 실거래 raw 수집 전담 — 가격지수·평균/중위 파생 통계는 itda-gov:realty-price-stats, 미분양·인허가·청약은 itda-gov:realty-supply."
pack: itda-gov
slug: realty-deals
status: active
tags: ["realestate", "molit", "trade", "rent", "csv", "json"]
---
# realty-deals 사용 가이드

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

---

## 처음 설정하기

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

1. [data.go.kr](https://www.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` 가 되어도 됩니다).

```dotenv
KO_DATA_API_KEY=발급받은_키
```

> 자세한 가입·키 발급 절차(Decoding 키 주의사항 포함)는 [공공데이터포털 발급 가이드](https://itda.work/credentials/data-go-kr/)를 참고하세요.

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 팩의 `realestate` 스킬을 쓰던 분은 `KO_DATA_API_KEY`를 그대로 사용하면 됩니다. 기존 4유형(아파트 매매·전월세, 오피스텔 매매·전월세)은 동일하게 동작합니다.

---

## 안 될 때

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