---
title: "realty-jeonse-gap"
description: "매매와 전월세 실거래를 단지·전용면적 기준으로 조인해 전세가율과 갭 투자 후보를 스크리닝하는 스킬입니다. \"강남구 아파트 전세가율 80% 넘는 단지 찾아줘\", \"분당 연립다세대 갭 3천만 이하 목록 뽑아줘\", \"전세가율 임계값 스크리닝 해줘\"처럼 말하면 됩니다."
pack: itda-gov
slug: realty-jeonse-gap
status: active
tags: ["jeonse", "gap", "screener", "realestate"]
---
# realty-jeonse-gap 사용 가이드

매매와 전월세 실거래를 단지·전용면적 기준으로 대조해 **전세가율**과 **갭**을 계산하고, 조건에 맞는 후보를 추려드립니다.
`/realty-jeonse-gap 강남구 아파트 전세가율 80% 넘는 단지 찾아줘`, `/realty-jeonse-gap 분당 연립다세대 갭 3천만 이하 목록 뽑아줘`처럼 말하면 됩니다.

---

## 처음 설정하기

이 스킬은 공공데이터포털 API 키가 필요합니다. 아파트 매매·전월세 두 서비스를 모두 신청해야 합니다.

1. [data.go.kr](https://www.data.go.kr)에 가입합니다.
2. 아파트 매매 실거래 서비스를 활용신청합니다: https://www.data.go.kr/data/15126469/openapi.do
3. 아파트 전월세 실거래 서비스를 활용신청합니다: https://www.data.go.kr/data/15126474/openapi.do
4. 발급받은 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분이 걸릴 수 있습니다. 신청 직후 오류가 나면 잠시 기다렸다가 다시 요청하세요.

---

## 계산 방식

| 지표 | 산식 |
|------|------|
| **전세가율** | 전세보증금 ÷ 매매가 × 100 (%) |
| **갭** | 매매가 − 전세보증금 (만원) |

동일 단지·전용면적에 전세 실거래가 여러 건이면 **최고 전세보증금**을 기준으로 계산합니다.

---

## 지원하는 부동산 유형

| 유형 | 설명 |
|------|------|
| 아파트 | 기본값 |
| 오피스텔 | `/realty-jeonse-gap 분당구 오피스텔 전세가율 스크리닝 해줘` |
| 연립다세대 | `/realty-jeonse-gap 마포구 연립다세대 갭 3천만 이하 목록 뽑아줘` |
| 단독다가구 | `/realty-jeonse-gap 성북구 단독다가구 전세가율 보여줘` |

---

## 자주 쓰는 요청

| 하고 싶은 것 | 이렇게 말하세요 |
|--------------|-----------------|
| 전체 전세가율·갭 산출 | `/realty-jeonse-gap 강남구 2026년 1~6월 아파트 전세가율과 갭 전체 보여줘` |
| 전세가율 높은 단지만 | `/realty-jeonse-gap 분당구 2026년 상반기 전세가율 80% 이상인 단지만 뽑아줘` |
| 갭 작은 단지만 | `/realty-jeonse-gap 마포구 2026년 1~6월 갭 3억 이하인 단지만 보여줘` |
| 두 조건 동시 적용 | `/realty-jeonse-gap 강남구 2026년 상반기 전세가율 80% 이상이고 갭 2억 이하인 단지 찾아줘` |
| 아파트 외 유형 | `/realty-jeonse-gap 분당구 오피스텔 전세가율 스크리닝 해줘` |

---

## 알아두면 좋은 점

- **조건 없이도 사용 가능**: 전세가율·갭 필터를 말하지 않으면 해당 지역·기간의 모든 단지 결과를 보여줍니다. 필터는 선택사항입니다.
- **복수 전세 처리**: 같은 단지·면적에 전세 거래가 여러 건이면 가장 높은 보증금을 기준으로 전세가율을 계산합니다.
- **기본 유형은 아파트**: 유형을 따로 말하지 않으면 아파트 실거래를 기준으로 스크리닝합니다.
- **지역명 인식 오류 시**: `/realty-jeonse-gap 법정동코드 11680으로 검색해줘`처럼 법정동코드(5자리)로 직접 지정할 수 있습니다.

---

## 안 될 때

| 증상 | 원인 / 해결 |
|------|-------------|
| "API 키가 없다"는 안내 (`config`) | **`.env` 파일**(또는 Claude 지침)에 `KO_DATA_API_KEY`가 없거나 비어 있음. 위 "처음 설정하기" 확인 |
| "지역을 모르겠다"는 안내 (`args`) | 지역명을 다시 말하거나 법정동코드 직접 지정을 요청 |
| API 서비스 오류 (`api`) | 공공데이터포털 활용신청 승인 상태를 확인하고 다시 요청 |
| 결과가 없음 | 해당 기간에 조건을 만족하는 실거래가 없을 수 있습니다. 기간을 늘리거나 조건을 완화해 다시 요청하세요 |