[클로드 시리즈_44] API/Agent/Sub-agent 개념 — [03] 코드 0줄로 부동산 시장 보고서 만드는 법

 

1. 공통 베이스 프롬프트 — 모든 레벨 맨 앞에 붙여 사용

모든 레벨 실습 앞에 붙여 사용할 공통 베이스 프롬프트를 제시합니다. 여기에는 API 정보, 요청 파라미터, 계산 기준, 집계 규칙, 단위 주의사항이 포함됩니다.

아래 프롬프트를 먼저 Claude Code에 넣고 시작하면 됩니다.

[활용 API]
- 출처: 공공데이터포털 / 국토교통부 상업업무용 부동산 매매 실거래가 자료
- 엔드포인트: https://apis.data.go.kr/1613000/RTMSDataSvcNrgTrade/getRTMSDataSvcNrgTrade
- 메서드: GET / 응답 포맷: XML
- 인증키(serviceKey): [본인키]

[요청 파라미터]
- LAWD_CD (필수, 5자리): 법정동코드 앞 5자리
   예) 11110=종로, 11140=중구, 11170=용산, 11200=성동, 11440=마포,
       11650=서초, 11680=강남
- DEAL_YMD (필수, 6자리): 계약년월 YYYYMM (예: 202603)
- numOfRows: 페이지당 건수 (기본 10, 최대 1000)
- pageNo: 페이지 번호 (기본 1)

[응답 구조]
response
 ├─ header.resultCode (00=정상) / resultMsg
 └─ body
     ├─ items.item[]   : 거래 리스트
     ├─ totalCount     : 전체 건수
     ├─ numOfRows / pageNo

[item 필드 명세]  ※ 금액 단위 = 만원, 면적 단위 = ㎡
- sggCd / sggNm        : 시군구 코드 / 이름
- umdNm                : 읍면동명 (예: 역삼동)
- jibun                : 지번 (일반건축물은 일부만 공개)
- buildingType         : 집합건물 / 일반건축물
- buildingUse          : 건물 주용도 (업무시설, 제2종근린생활시설 등)
- landUse              : 용도지역 (일반상업지역, 준주거지역 등)
- dealYear / dealMonth / dealDay : 계약일
- floor                : 층
- buildYear            : 준공년도
- dealAmount           : 거래금액 (만원, 콤마 포함 문자열)
- plottageAr           : 대지면적 (㎡)
- buildingAr           : 건물(전용)면적 (㎡)
- shareDealingType     : 지분 / 일반
- dealingGbn           : 중개거래 / 직거래
- estateAgentSggNm     : 중개사 소재 시군구
- slerGbn / buyerGbn   : 매도자/매수자 구분 (개인/법인/공공기관/기타)
- cdealType            : 해제여부 (O=해제)
- cdealDay             : 해제사유 발생일

[파생 지표 계산 규칙]
- 평당가(만원/평) = dealAmount ÷ (buildingAr × 0.3025)
- 건물 연식 = dealYear − buildYear
- 거래금액 구간: 50억 미만 / 50~200억 / 200억 이상  (1억 = 10,000만원)
- 집계 시 cdealType == "O" 인 해제건은 제외

[규칙]
- 숫자는 반드시 데이터 근거 함께 제시. 추정/일반론은 "추정"으로 표기.
- 응답 단위(만원, ㎡)를 절대 헷갈리지 말 것.
- 결과는 마크다운 표 + 짧은 코멘트 위주로 정리.

해제건 제외, 거래금액 구간, 건물 연식 계산, 단위 혼동 주의, 추정 표시, 마크다운 표 중심 정리를 핵심 규칙으로 제시합니다.

2. Level 1 — 단순 조회로 감 잡기

처음부터 복잡한 분석을 시키지 않습니다.

먼저 API가 정상적으로 호출되는지, 데이터가 어떤 형식으로 들어오는지 확인합니다.

첨부 글의 Level 1은 서울 강남구 2026년 3월 거래 10건을 호출하고, 핵심 컬럼만 표로 정리하는 실습입니다.

실행 프롬프트

[요청]
서울 강남구(LAWD_CD=11680) 2026년 3월(DEAL_YMD=202603) 거래 10건을 호출해줘.

결과는 아래 컬럼만 표로 정리해줘.

계약일 | 동(umdNm) | 건물유형 | 주용도 | 거래금액(억원) | 전용면적(㎡) | 평당가(만원/평) | 준공년도

표 아래에 한 줄로
“이 10건의 평균 거래금액 / 평균 평당가”를 요약해줘.

[주의]
- serviceKey는 출력하지 마.
- 거래금액 단위를 헷갈리지 마.
- 평당가 계산식은 표 아래에 함께 표시해줘.

 

기대 결과

항목	확인 내용
API 연결	정상 호출 여부
데이터 구조	어떤 필드가 들어오는지
단위 확인	거래금액, 면적 단위
계산 확인	평당가 계산 가능 여부
요약 확인	평균 거래금액과 평균 평당가

이 단계의 의미

Level 1은 분석이 아니라 감 잡기입니다.

데이터가 들어오는가?
필드명이 무엇인가?
금액 단위가 무엇인가?
평당가 계산이 되는가?
Claude Code가 표로 잘 정리하는가?

 

이 네 가지를 확인하면 됩니다.

---

3. Level 2 — 단일 지역 12개월 트렌드

Level 1에서 한 달치 일부 데이터를 확인했다면, 이제 12개월 흐름을 봅니다.

첨부 글의 Level 2는 서울 중구(LAWD_CD=11140)의 2025년 4월부터 2026년 3월까지 12개월 데이터를 월별로 호출하고, 거래건수·평균 거래금액·평당가 추이를 집계하는 실습입니다.

실행 프롬프트

[요청]
서울 중구(LAWD_CD=11140)의 DEAL_YMD 2025-04 ~ 2026-03, 총 12개월 거래를 모두 호출해줘.

월별로 12번 호출하고, 각 월은 numOfRows=1000으로 페이징 처리해줘.

집계해서 다음 4개 표와 짧은 코멘트를 작성해줘.

1. 월별 거래건수 / 평균 거래금액(억) / 평균 평당가(만원/평) 추이
2. umdNm(동)별 거래건수 Top 5와 평당가
3. buildingUse(주용도)별 거래 비중(%)
4. dealingGbn 기준 “직거래 비중” 월별 추이

마지막에 인사이트 3줄을 써줘.
- 시장 분위기: 활발 / 둔화
- 동·용도 측면 핫스팟
- 직거래 비중에서 읽히는 변화

[주의]
- 해제건은 제외해줘.
- 숫자는 반드시 데이터 근거와 함께 제시해줘.
- 추정은 “추정”으로 표시해줘.

 

이 단계의 의미

Level 2부터는 단순 조회가 아니라 시장 흐름 분석입니다.

한 달만 보면 우연일 수 있습니다.
12개월을 보면 방향성이 보입니다.

거래가 늘고 있는가?
평당가가 올라가는가?
특정 동에 거래가 몰리는가?
직거래 비중이 달라지는가?

 

이 질문에 답하는 단계입니다.

---

4. Level 3 — 5개 구 비교 인사이트

Level 3은 5개 지역을 대상으로 5개 지표를 비교하는 구조입니다. 비교 항목에는 거래량, 평균 거래금액, 평균 평당가, 거래금액 구간, 건물 연식, 매수자 유형 비중 등이 포함됩니다.

실행 프롬프트

[요청]
서울 핵심 5개 구의 2026-Q1 (DEAL_YMD 202601, 202602, 202603) 상업업무용 부동산 매매 실거래 데이터를 비교해줘.

대상 지역:
- 종로구 11110
- 중구 11140
- 용산구 11170
- 성동구 11200
- 마포구 11440

다음 5개 항목을 5x5 비교표로 정리해줘.

A. 거래량: 거래건수
B. 가격 수준: 평균 거래금액(억) / 평균 평당가(만원/평)
C. 거래금액 구간 비중: 50억 미만 / 50~200억 / 200억 이상
D. 건물 연식: 신축(5년 이내) / 일반(5~20년) / 노후(20년 초과) 비중
E. 매수자 유형 비중: buyerGbn 기준 개인 vs 법인

결과:
1. 위 5개 항목별 5x5 비교표
2. “가장 활발한 시장” 1곳과 근거
3. “가장 식은 시장” 1곳과 근거
4. 법인 매수 비중이 가장 높은 구 1곳과 의미 해석

[주의]
- 데이터가 부족한 구는 “데이터 부족”으로 표시해줘.
- 단정하지 말고 근거 기반으로 해석해줘.

 

이 단계의 의미

Level 3은 상대 비교입니다.

부동산 시장은 절대값보다 비교가 중요합니다.

어느 구가 더 활발한가?
어느 구가 더 고가 거래가 많은가?
어느 구가 법인 매수가 강한가?
어느 구가 노후 건물 거래 위주인가?

 

이런 질문에 답할 수 있습니다.

---

5. Level 4 — 투자·사업 관점 분기 브리프

Level 4는 실무 보고서입니다.

Level 4에서 학습자가 자신의 역할을 넣도록 안내합니다. 예를 들어 중소형 빌딩 투자자, 리테일 출점 담당자, 상권분석가 같은 역할을 넣고, 2026년 1분기 서울 상업용 부동산 시장 브리프를 A4 1장 분량으로 작성하게 합니다.

실행 프롬프트

[요청]
내 역할: [중소형 빌딩 투자자]

이 API 데이터로 “2026년 1분기 서울 상업용 부동산 시장 브리프”를 A4 1장 분량으로 작성해줘.

[호출 범위]
서울 핵심 8개 구 × 202601~202603

대상 지역:
- 11110 종로
- 11140 중구
- 11170 용산
- 11200 성동
- 11215 광진
- 11440 마포
- 11650 서초
- 11680 강남

[리포트 구성]
1. 헤드라인 숫자 3개
   - 분기 총 거래건수
   - 평균 평당가
   - YoY 변화가 가능하면 포함

2. 핫 지역 Top 3
   - 데이터 근거: 거래량, 평당가, 법인매수 등

3. 식고 있는 지역 Top 3
   - 데이터 근거 포함

4. 매도자·매수자 유형 변화
   - slerGbn, buyerGbn 기준

5. 다음 분기 모니터링 포인트 2가지

6. 근거 표 1개
   - 지역 × 지표 매트릭스
   - 본문 하단 첨부

[톤]
- 사실 위주
- 추정에는 반드시 “추정” 표기
- 투자 권유처럼 쓰지 말 것
- 데이터에 없는 내용은 단정하지 말 것

 

브리프 구성 예시

제목:
2026년 1분기 서울 상업용 부동산 시장 브리프

1. 헤드라인 숫자
- 총 거래건수:
- 평균 평당가:
- 법인 매수 비중:

2. 핫 지역 Top 3
- 1위:
- 2위:
- 3위:

3. 식고 있는 지역 Top 3
- 1위:
- 2위:
- 3위:

4. 매수자 유형 변화
- 개인:
- 법인:
- 기타:

5. 다음 분기 모니터링 포인트
- 고가 거래 지속 여부
- 법인 매수 비중 변화

 

이 단계의 의미

Level 4는 단순 분석이 아니라 의사결정용 브리프입니다.

사용자 역할에 따라 같은 데이터도 해석이 달라집니다.

역할	관심 포인트
중소형 빌딩 투자자	평당가, 고가 거래, 법인 매수
리테일 출점 담당자	거래 활발 지역, 상권 변화
상권분석가	동별 거래, 용도별 비중
정책 담당자	거래 위축 지역, 지역 간 격차
교육 강사	데이터 분석 실습 사례

 

---

6. Level 5 — 자동 갱신 위클리 트래커 페이지 만들기

Level 5는 보고서를 넘어 대시보드 페이지 발주로 확장합니다.

Level 5에서 이 API를 호출해 매주 갱신되는 서울 상업용 부동산 위클리 트래커 페이지를 만들도록 요청합니다.

실행 프롬프트

[요청]
이 API를 호출해서 매주 갱신되는 "서울 상업용 부동산 위클리 트래커" 페이지를 만들어줘.
(HTML 단일 파일, 차트는 Chart.js, 표는 Grid.js, 갱신 시 API 재호출)

대상: 서울 25개 구 전체, 기간 = 최근 3개월 (DEAL_YMD 자동 계산)

레이아웃:
[상단 KPI 카드 4개]
 - 최근월 거래건수 (전월 대비 ▲/▼ %)
 - 최근월 평균 거래금액(억)
 - 최근월 평균 평당가(만원/평)
 - 최근월 법인 매수자 비중(%)

[중단]
 - 서울 25개 구 평당가 히트맵 (또는 막대그래프)
 - 월별 거래량 추세 라인차트 (최근 12개월)

[하단]
 - 최근월 거래금액 Top 20 거래 테이블
   컬럼: 구·동·주용도·거래금액(억)·전용면적·평당가·준공년도·거래유형

[필터]
 - 지역 다중선택 / 기간(3·6·12개월) / 건물용도

[표시 규칙]
 - 단위 명시 (만원·㎡·평·억)
 - 해제건(cdealType=O) 제외
 - 데이터 출처/갱신시각 푸터에 표기

[디자인]
- 밝은 배경
- 카드형 레이아웃
- 표 중심
- 모바일에서도 볼 수 있는 반응형
- 숫자는 크게 강조

[주의]
- API Key는 HTML 안에 노출하지 마.
- 실제 서비스 배포 시 API Key는 서버 또는 환경변수로 관리해야 한다고 안내문을 넣어줘.
- 데이터가 없거나 오류가 나면 “데이터 없음” 또는 “API 응답 확인 필요”로 표시해줘.

 

이 단계의 의미

Level 5는 Claude Code에게 단순 분석이 아니라 서비스 형태의 결과물을 요구하는 단계입니다.

표 분석
→ 보고서
→ 대시보드
→ 자동 갱신형 페이지

 

이 흐름을 익히면 다른 분야에도 적용할 수 있습니다.

분야	트래커 예시
부동산	상업용 부동산 위클리 트래커
관광	제주 관광지 방문 트렌드
날씨	지역별 미세먼지 모니터링
선거	지역별 공약·여론 데이터 정리
교육	AI 뉴스·공공기관 공지 트래커
마케팅	캠페인 성과 주간 대시보드

---

7. 핵심 지표 해석법

부동산 시장 보고서는 숫자를 나열하는 것이 아닙니다.
숫자에서 의미를 읽어야 합니다.

1) 거래건수

거래건수는 시장의 활기를 보여 줍니다.

신호	해석
거래건수 증가	시장 관심 증가 가능성
거래건수 감소	관망세 또는 유동성 저하 가능성
특정 동 거래 집중	국지적 수요 가능성
거래 거의 없음	판단 보류 필요

2) 평균 거래금액

평균 거래금액은 거래되는 물건의 가격대를 보여 줍니다.

하지만 평균만 보면 위험합니다.

대형 빌딩 1건이 평균을 크게 끌어올릴 수 있음
소액 거래가 많으면 평균이 낮아질 수 있음

 

그래서 거래금액 구간을 함께 봐야 합니다.

50억 미만
50억~200억
200억 이상

 

3) 평당가

평당가는 면적 대비 가격 수준을 보여 줍니다.

첨부 글은 평당가 계산 기준으로 거래금액 ÷ (면적 × 0.3025)를 사용하도록 안내합니다.

평수 = 전용면적(㎡) × 0.3025
평당가 = 거래금액(만원) ÷ 평수

 

주의할 점은 거래금액 단위입니다.

공공데이터 응답의 거래금액은 보통 만원 단위입니다.
따라서 억 원, 만원, 평당가 단위를 혼동하면 보고서 전체가 틀어집니다.

4) 고가 거래 비중

고가 거래 비중은 큰 자금이 들어오는지를 보는 지표입니다.

구간	해석
50억 미만	중소형 거래
50억~200억	중대형 거래
200억 이상	대형 거래, 기관·법인 가능성

고가 거래가 많다고 무조건 좋은 것은 아닙니다.
거래건수와 함께 봐야 합니다.

5) 건물 연식

건물 연식은 매입 목적을 추정할 때 도움이 됩니다.

구분	기준	해석
신축	5년 이내	안정적 임대수익, 신축 프리미엄 가능성
일반	5~20년	일반 거래
노후	20년 초과	리모델링, 재개발, 밸류애드 가능성

신축, 일반, 노후 구간을 5년 이내, 5~20년, 20년 초과로 나누어 비교하도록 안내합니다.

---

6) 법인 매수 비중

법인 매수 비중은 전문 투자자나 사업자의 움직임을 읽는 데 참고할 수 있습니다.

신호	해석
법인 매수 증가	사업성 또는 투자성 관심 가능성
개인 매수 중심	개별 투자자 중심 시장 가능성
법인 매수 급감	기관성 수요 약화 가능성
데이터 부족	해석 보류

단, 법인 매수가 많다고 무조건 상승을 뜻하지 않습니다.
업종, 위치, 거래금액, 건물 용도와 함께 봐야 합니다.

---

8. Claude Code에게 맡길 때 좋은 순서

한 번에 최종 보고서를 만들라고 하면 오류가 날 수 있습니다.

다음 순서로 진행하는 것이 안전합니다.

1단계: API 연결 테스트
2단계: 단일 지역 10건 조회
3단계: 단일 지역 12개월 추이
4단계: 여러 지역 비교
5단계: 분기 브리프 작성
6단계: HTML 대시보드 발주

 

이 흐름은 글의 Level 1~5 구조와 같습니다. 단순 조회에서 시작해 12개월 트렌드, 지역 비교, 분기 브리프, 자동 갱신형 트래커로 확장하는 방식입니다.

---

9. 실무 응용 예시

1) 상권분석가용

내 역할은 상권분석가입니다.

서울 핵심 8개 구의 상업업무용 부동산 실거래 데이터를 바탕으로
상권 변화가 뚜렷한 지역 Top 3를 찾아 주세요.

거래량, 평당가, 주용도, 법인 매수 비중을 근거로 분석해 주세요.

 

2) 리테일 출점 담당자용

내 역할은 리테일 출점 담당자입니다.

2026년 1분기 서울 상업용 부동산 거래 데이터를 바탕으로
출점 후보 지역을 검토해 주세요.

단, 투자 권유가 아니라 후보 지역 선별용 참고 보고서로 작성해 주세요.

 

3) 중소형 빌딩 투자자용

내 역할은 중소형 빌딩 투자자입니다.

50억~200억 구간 거래가 활발한 지역을 중심으로
서울 핵심 구별 중소형 빌딩 거래 흐름을 정리해 주세요.

법인 매수 비중과 건물 연식을 함께 분석해 주세요.

 

4) 공공기관 정책 담당자용

내 역할은 지역경제 정책 담당자입니다.

서울 핵심 8개 구의 상업업무용 부동산 거래를 비교해
상업 활동이 활발한 지역과 둔화된 지역을 구분해 주세요.

정책적 시사점은 추정으로 표시해 주세요.

 

5) AI 데이터 분석 강의용

이 실거래가 API 데이터를 활용해
비개발자 대상 AI 데이터 분석 실습 교안을 만들어 주세요.

구성:
1. API란 무엇인가
2. 지역코드와 계약월 이해
3. Claude Code로 데이터 호출
4. 표 정리
5. 평당가 계산
6. 시장 보고서 작성

 

---

10. 오류가 날 때 확인할 것

증상	가능한 원인	해결
API 응답 없음	인증키 오류	serviceKey 재확인
resultCode가 00이 아님	요청 파라미터 오류	LAWD_CD, DEAL_YMD 확인
totalCount가 0	해당 기간 거래 없음	다른 월 또는 지역 조회
금액이 이상함	만원·억원 단위 혼동	거래금액 단위 재확인
평당가가 과도하게 높음	면적 변환 오류	㎡ × 0.3025 확인
해석이 과장됨	프롬프트에 제한 조건 없음	“추정 표시, 투자 권유 금지” 추가
HTML에 API Key 노출	클라이언트 코드에 키 삽입	환경변수 또는 서버 처리 안내

---

11. Q&A — 자주 묻는 질문 5가지

Q1. 정말 코드를 한 줄도 몰라도 가능한가요?

가능합니다. 사용자가 직접 코드를 쓰지 않아도 Claude Code에게 API 정보, 조회 조건, 계산 기준, 출력 형식을 프롬프트로 알려 주면 됩니다. 다만 API Key, 지역코드, 계약월, 단위 같은 기본 개념은 이해해야 합니다.

Q2. 이 데이터로 아파트 시장 보고서도 만들 수 있나요?

이번 실습의 API는 상업업무용 부동산 매매 실거래가 자료입니다. 아파트 시장을 분석하려면 아파트 실거래가 API를 별도로 사용해야 합니다. 상업용 데이터와 주거용 데이터를 섞으면 안 됩니다.

Q3. 평당가는 어떻게 계산하나요?

전용면적이 ㎡로 제공되므로 먼저 평으로 바꿉니다.

평수 = 전용면적(㎡) × 0.3025
평당가 = 거래금액(만원) ÷ 평수

 

이때 거래금액은 만원 단위이므로 억 원 단위로 착각하면 안 됩니다.

Q4. 가격 전망을 보고서에 써도 되나요?

쓸 수는 있지만 반드시 조심해야 합니다. “상승 확정”, “투자 적기”처럼 단정하면 안 됩니다. “현재 데이터 기준 상승 가능성이 관찰됩니다”, “추가 확인이 필요합니다”처럼 근거 기반 추정으로 표현해야 합니다.

Q5. HTML 대시보드에 API Key를 넣어도 되나요?

권장하지 않습니다. HTML에 API Key를 넣으면 사용자가 페이지 소스에서 키를 볼 수 있습니다. 실제 서비스에서는 서버 또는 환경변수로 관리해야 합니다. 실습용으로도 공개 배포 전에는 키가 노출되지 않았는지 반드시 확인해야 합니다.

---

12. 핵심 정리

코드 0줄 부동산 시장 보고서는 Claude Code와 공공데이터 API를 연결해 만드는 데이터 분석 실습입니다.

핵심은 코딩이 아니라 프롬프트 설계입니다.

어떤 API를 쓸 것인가
어떤 지역을 볼 것인가
어떤 기간을 볼 것인가
어떤 지표를 계산할 것인가
어떤 표현은 조심할 것인가

 

실습은 Level 1부터 시작합니다.

Level 1: 강남구 10건 단순 조회
Level 2: 중구 12개월 트렌드
Level 3: 서울 5개 구 비교
Level 4: 2026년 1분기 시장 브리프
Level 5: 자동 갱신 위클리 트래커 페이지

 

분석할 때는 거래건수, 평균 거래금액, 평당가, 고가 거래 비중, 건물 연식, 법인 매수 비중을 함께 봐야 합니다.

가장 중요한 주의사항은 세 가지입니다.

API Key는 공개하지 않는다.
만원과 ㎡ 단위를 헷갈리지 않는다.
가격 전망은 확정이 아니라 추정으로 표현한다.

 

마지막으로 이 문장을 기억하면 됩니다.

코드 0줄 부동산 보고서의 핵심은 AI에게 코드를 맡기는 것이 아니라, 사람이 분석 기준과 안전 기준을 정확히 설계하는 것입니다.

---

작성자 프로필

강호종 AI 길라잡이 강사

​생성형 AI 활용 업무 효율화 전문강사 · 디지털융합교육원 지도강사 & AI 전문강사, 젠스파크 AI 전문강사 · (사)한국AINFT협회 이사
저서: 『생성형 AI 활용 업무혁신』(2026.1) · 『이것이 GEO마케팅이다』(2026) 외
📞 010-9912-9934 | 📧 art386@naver.com | Ⓑ blog.naver.com/art386 | Ⓣ aiart386.tistory.com

​생성형 AI, AI 리터러시, ChatGPT·Claude·Gemini 실무 활용, AI 업무 자동화, GEO마케팅을 중심으로 공공기관·기업·단체 대상 강의와 콘텐츠를 제작합니다.

---

메타 설명

Claude Code와 공공데이터포털 부동산 실거래가 API를 활용해 코드 0줄로 상업용 부동산 시장 보고서를 만드는 실습 글입니다. 강남구 단순 조회, 중구 12개월 트렌드, 서울 핵심 구 비교, 분기 브리프, 위클리 트래커 대시보드 발주 프롬프트까지 정리했습니다.

---

해시태그

#클로드시리즈 #ClaudeCode #공공데이터API #부동산실거래가 #상업용부동산 #시장보고서 #코드없이분석 #API활용 #MCP #Agent #Subagent #AI데이터분석 #AI업무자동화 #AI리터러시 #생성형AI강의 #AI강사 #강호종강사 #Claude활용 #ChatGPT활용 #GEO마케팅