# 데이터 수집 가이드: 서울 아파트 매매부터 API 활용까지

- 작성자: [반짝이는 고양이](https://community.clauders.ai/member/imported-member-eqi7HibQOn)
- 공간: [바이브 코딩](https://community.clauders.ai/claude-code)
- 게시: 2026-07-26
- 연재: [데이터 수집과 대시보드](https://community.clauders.ai/series/data-dashboard-workshop) 1/2편
- 태그: #데이터대시보드
- 주소: https://community.clauders.ai/claude-code/post/%EB%8D%B0%EC%9D%B4%ED%84%B0-%EC%88%98%EC%A7%91-%EA%B0%80%EC%9D%B4%EB%93%9C-%EC%84%9C%EC%9A%B8-%EC%95%84%ED%8C%8C%ED%8A%B8-%EB%A7%A4%EB%A7%A4%EB%B6%80%ED%84%B0-api-%ED%99%9C%EC%9A%A9%EA%B9%8C%EC%A7%80-95efbc5e-4c1b-8c7a-8e47-fa8ecaa3f5ab

---

## **데이터 수집 목표**

데이터·투자·재테크 스터디 1주차 실습을 따라, 서울 아파트 매매/전월세 실거래가(국토교통부 API), KB통계(아파트 가격지수), 주식/지수 데이터(삼성전자 등 대표 종목 + KOSPI/KOSDAQ)를 각각 API로 수집해서 로컬 DuckDB 하나에 정리해보고 싶었습니다.

## **활용한 도구**

- **Claude Code**: 프로젝트 초기 세팅부터 수집 스크립트 작성, 에러 디버깅까지 전 과정을 대화로 진행
- **UV**: 파이썬 가상환경/의존성 관리
- **DuckDB + Polars**: 데이터 저장 및 처리 (Pandas 대신 Polars 사용 — 스터디에서 강조한 메모리 이슈 회피 팁)
- **공공데이터포털 API**: 국토교통부 아파트 매매/전월세 실거래가
- **PublicDataReader**: KB통계(가격지수) — API 키 불필요
- **FinanceDataReader**: 주식/지수 데이터 — API 키 불필요

## **데이터 수집 과정**

1. 실습 전용 폴더를 따로 만들고 `uv init` + `uv venv`로 가상환경 구성, `duckdb`/`polars`/`publicdatareader`/`finance-datareader` 설치
2. [CLAUDE.md](http://CLAUDE.md)에 "Pandas 대신 Polars 우선 사용" 정책을 문서화해 이후 모든 작업에 자동 반영되게 함
3. 공공데이터포털에서 아파트 매매 실거래·전월세 실거래 두 API를 각각 활용신청 → 승인 후 인증키를 `.env`에 저장(키는 채팅창에 입력하지 않고 파일을 직접 열어 입력)
4. 서울 25개 구 × 2025년 1월~2026년 6월 범위로 매매/전월세 데이터를 API로 수집해 DuckDB에 적재
5. KB통계(아파트 매매/전세 가격지수, 월간)를 PublicDataReader로 수집
6. 삼성전자 등 5개 종목 + KOSPI/KOSDAQ 지수를 FinanceDataReader로 수집

## **시행착오와 해결책**

- **전월세 API 403 에러**: 매매 API는 바로 승인·정상 동작했는데 전월세 API는 승인 직후 한동안 403이 남. 시간을 두고 재시도하니 정상화됨 — 승인 반영에 지연이 있을 수 있다는 걸 배움
- **DuckDB ↔ Polars 연동 에러**: `pyarrow` 패키지가 없어서 첫 수집 시도(서울 25개 구 전체, 약 20분 소요)가 저장 단계에서 실패. 라이브러리를 추가하고 처음부터 다시 수집해야 했음 → 앞으로는 저장 로직까지 먼저 소규모로 검증한 뒤 전체 수집을 돌리는 게 낫겠다고 판단
- **KB통계 API 연결 끊김**: PublicDataReader 라이브러리의 특정 함수가 브라우저 User-Agent 헤더 없이 요청을 보내서 KB 서버가 연결을 끊는 문제가 있었음. 요청에 User-Agent 헤더를 직접 주입해서 우회

## **배운 점과 향후 계획**

- 같은 계정의 인증키라도 API별로 승인 반영 시점이 다를 수 있다는 것
- 대용량 데이터를 다룰 때 저장 파이프라인(이번엔 DuckDB 연동)까지 사전 검증하지 않으면, 수집 자체는 성공해도 마지막에 전부 날아갈 수 있다는 것
- 공공 API라도 서버마다 요구하는 요청 조건(헤더 등)이 다를 수 있어, 라이브러리를 그대로 믿기보다 응답을 직접 확인하는 습관이 필요하다는 것
- 2주차 실습(Streamlit 대시보드 제작)에 이 데이터를 바로 활용
- 매일 자동 수집되는 스케줄러(크론잡) 추가는 아직 안 했음 — 필요해지면 진행 예정
- 수집 범위를 서울 전체에서 관심 지역/종목으로 넓히는 것은 추후