---
title: "realty-supply"
description: "KOSIS 주택 공급 지표(미분양·인허가·착공·준공·입주)와 청약홈 청약 통계를 수집하는 스킬입니다. \"올해 강남구 아파트 미분양 추이 보여줘\", \"2024년 전국 인허가·착공·준공 통계 가져와줘\", \"최근 청약 경쟁률 높은 단지 목록 보여줘\"처럼 말하면 됩니다. [책임 경계] 본 스킬은 KOSIS 공급 지표·청약 통계 전담 — 개별 실거래 원본은 itda-gov:realty-deals, 가격지수·파생 통계는 itda-gov:realty-price-stats."
pack: itda-gov
slug: realty-supply
status: active
tags: ["KOSIS", "supply", "subscription", "housing"]
---
# realty-supply 사용 가이드

KOSIS(국가통계포털) 주택 공급 지표(미분양·인허가·착공·준공)와 청약홈 청약 통계를 수집합니다.
`/realty-supply 올해 전국 아파트 미분양 추이 보여줘`, `/realty-supply 2024년 전국 인허가·착공·준공 통계 가져와줘`처럼 말하면 됩니다.

---

## 처음 설정하기

### KOSIS 공급 지표 조회

KOSIS Open API 키가 필요합니다.

1. [kosis.kr](https://kosis.kr/openapi/)에 회원가입합니다.
2. Open API 활용신청을 합니다: https://kosis.kr/openapi/index/index.jsp
3. 발급받은 키를 **`.env` 파일에 넣습니다 (권장)** — 작업 폴더(Cowork 연결 폴더 / Claude Code 프로젝트 루트)(연결한 폴더가 여러 개면 아무 폴더나) 루트에 `.env` 파일을 만들고 아래 한 줄을 넣어 두면 스킬이 자동으로 찾아 읽습니다. 점(`.`)으로 시작하는 파일을 만들기 어렵다면 **`환경변수.txt`** 라는 이름으로 만들어도 똑같이 읽힙니다(메모장이 `.txt` 를 붙여 `.env.txt` 가 되어도 됩니다).

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

> KOSIS 가입·키 발급 절차는 [KOSIS 발급 가이드](https://itda.work/credentials/kosis/)를 참고하세요.

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

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

### 청약홈 청약 통계 추가 조회

청약 경쟁률·분양 데이터를 함께 보려면 공공데이터포털 키도 필요합니다. `realty-deals` 스킬을 이미 쓰고 있다면 같은 키를 그대로 씁니다. 이 키도 같은 `.env` 파일에 한 줄 추가하면 됩니다.

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

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

> 청약 경쟁률 데이터는 **2020년 2월부터** 제공됩니다. 그 이전 구간은 조회되지 않습니다.

---

## 지원하는 지표

| 지표 | 설명 | 활용 예 |
|------|------|---------|
| 미분양 | 팔리지 않은 신규 분양 주택 수 | 공급 과잉·해소 추적 |
| 인허가 | 신규 주택 건설 허가 건수 | 향후 공급 선행지표 |
| 착공 | 공사를 시작한 주택 수 | 공급 진행 단계 파악 |
| 준공 | 공사가 완료된 주택 수 | 입주 물량 추정 |
| 청약 통계 | 청약홈 경쟁률·분양 데이터 | 청약 수요 분석 |

---

## 자주 쓰는 요청

| 하고 싶은 것 | 이렇게 말하세요 |
|--------------|-----------------|
| 미분양 추이 조회 | `/realty-supply 2024년 전체 미분양 월별 추이 보여줘` |
| 인허가 현황 | `/realty-supply 2026년 1~6월 전국 인허가 통계 가져와줘` |
| 착공·준공 조회 | `/realty-supply 2024년 착공 및 준공 수치 같이 보여줘` |
| 청약 경쟁률 | `/realty-supply 2026년 1~6월 청약 경쟁률과 분양 데이터 보여줘` |
| 여러 지표 한 번에 | `/realty-supply 2024년 인허가·착공·준공 세 지표 다 보여줘` |

---

## 알아두면 좋은 점

- **청약 데이터 시작 시점**: 청약 경쟁률 데이터는 2020년 2월부터 제공됩니다. 그 이전 기간을 요청해도 데이터가 없으며, 없는 구간에 데이터를 만들어 채우지 않습니다.
- **선행지표로 활용**: 인허가 → 착공 → 준공 순서로 공급 파이프라인을 파악할 수 있습니다. `/realty-supply 인허가부터 준공까지 전 단계 보여줘`처럼 한 번에 요청해도 됩니다.

---

## 안 될 때

| 증상 | 원인 / 해결 |
|------|-------------|
| "KOSIS 키가 없다"는 안내 (`config`) | **`.env` 파일**(또는 Claude 지침)에 `KOSIS_API_KEY`가 없거나 비어 있음. 위 "처음 설정하기" 확인 |
| "공공데이터 키가 없다"는 안내 (`config`) | 청약 데이터 요청 시 `KO_DATA_API_KEY`도 필요. **`.env` 파일**(또는 Claude 지침)에 추가 |
| API 서비스 오류 (`api`) | 각 포털 활용신청 승인 상태를 확인하고 다시 요청 |
| 청약 데이터가 없음 | 2020년 2월 이전 구간은 데이터가 제공되지 않습니다 |