jaehwang
/
jhhackaton
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
jhhackaton/docs/api_guide.md

429 lines
17 KiB
Markdown
Raw Blame History

# 부동산 정보 검색 API 가이드
## 1. 공공데이터 API (국토교통부)
### 1.1 아파트 매매 실거래가 API
- **서비스명**: 국토교통부_아파트 매매 실거래가 자료
- **제공기관**: 국토교통부
- **URL**: https://www.data.go.kr/data/15126469/openapi.do
- **Base URL**: `apis.data.go.kr/1613000/RTMSDataSvcAptTrade`
- **엔드포인트**: `/getRTMSDataSvcAptTrade`
- **데이터 형식**: XML
- **트래픽 제한**: 개발계정 10,000/일
#### 주요 파라미터
- `serviceKey`: 공공데이터포털에서 발급받은 인증키
- `LAWD_CD`: 법정동 코드 5자리 (예: 서울 종로구 11110)
- `DEAL_YMD`: 계약년월 6자리 (예: 202501)
### 1.2 아파트 전월세 실거래가 API
- **서비스명**: 국토교통부_아파트 전월세 실거래가 자료
- **제공기관**: 국토교통부
- **URL**: https://www.data.go.kr/data/15126474/openapi.do
- **Base URL**: `apis.data.go.kr/1613000/RTMSDataSvcAptRent`
- **엔드포인트**: `/getRTMSDataSvcAptRent`
- **데이터 형식**: XML
- **트래픽 제한**: 개발계정 10,000/일
#### 주요 파라미터
- `serviceKey`: 공공데이터포털에서 발급받은 인증키
- `LAWD_CD`: 법정동 코드
- `DEAL_YMD`: 계약년월
### 1.3 연립/다세대 주택 실거래가 API
- **서비스명**: 국토교통부_연립다세대 매매/전월세 실거래가 자료
- **제공기관**: 국토교통부
- **URL**:
- 매매: https://www.data.go.kr/data/15126467/openapi.do
- 전월세: https://www.data.go.kr/data/15126473/openapi.do
- **Base URL**:
- 매매: `apis.data.go.kr/1613000/RTMSDataSvcSHTrade`
- 전월세: `apis.data.go.kr/1613000/RTMSDataSvcSHRent`
- **엔드포인트**:
- 매매: `/getRTMSDataSvcSHTrade`
- 전월세: `/getRTMSDataSvcSHRent`
- **데이터 형식**: XML
- **트래픽 제한**: 개발계정 10,000/일
### 1.4 오피스텔 실거래가 API
- **서비스명**: 국토교통부_오피스텔 매매/전월세 실거래가 자료
- **제공기관**: 국토교통부
- **URL**:
- 매매: https://www.data.go.kr/data/15126464/openapi.do
- 전월세: https://www.data.go.kr/data/15126475/openapi.do
- **Base URL**:
- 매매: `apis.data.go.kr/1613000/RTMSDataSvcOffiTrade`
- 전월세: `apis.data.go.kr/1613000/RTMSDataSvcOffiRent`
- **엔드포인트**:
- 매매: `/getRTMSDataSvcOffiTrade`
- 전월세: `/getRTMSDataSvcOffiRent`
- **데이터 형식**: XML
- **트래픽 제한**: 개발계정 10,000/일
### 1.5 단독/다가구 주택 실거래가 API
- **서비스명**: 국토교통부_단독다가구 매매/전월세 실거래가 자료
- **제공기관**: 국토교통부
- **URL**:
- 매매: https://www.data.go.kr/data/15126465/openapi.do
- 전월세: https://www.data.go.kr/data/15126472/openapi.do
- **Base URL**:
- 매매: `apis.data.go.kr/1613000/RTMSDataSvcSHHouseTrade`
- 전월세: `apis.data.go.kr/1613000/RTMSDataSvcSHHouseRent`
- **엔드포인트**:
- 매매: `/getRTMSDataSvcSHHouseTrade`
- 전월세: `/getRTMSDataSvcSHHouseRent`
- **데이터 형식**: XML
- **트래픽 제한**: 개발계정 10,000/일
### 1.6 토지 실거래가 API
- **서비스명**: 국토교통부_토지 매매 실거래가 자료
- **제공기관**: 국토교통부
- **URL**: https://www.data.go.kr/data/15126466/openapi.do
- **Base URL**: `apis.data.go.kr/1613000/RTMSDataSvcLandTrade`
- **엔드포인트**: `/getRTMSDataSvcLandTrade`
- **데이터 형식**: XML
- **트래픽 제한**: 개발계정 10,000/일
### 1.7 상업/업무용 부동산 실거래가 API
- **서비스명**: 국토교통부_상업업무용 부동산 매매 실거래가 자료
- **제공기관**: 국토교통부
- **URL**: https://www.data.go.kr/data/15126463/openapi.do
- **Base URL**: `apis.data.go.kr/1613000/RTMSDataSvcNrgTrade`
- **엔드포인트**: `/getRTMSDataSvcNrgTrade`
- **데이터 형식**: XML
- **트래픽 제한**: 개발계정 10,000/일
## 2. 한국부동산원 API
### 2.1 부동산 통계 조회 서비스
- **서비스명**: 한국부동산원_부동산통계 조회 서비스
- **제공기관**: 한국부동산원
- **URL**: https://www.data.go.kr/data/15134761/openapi.do
- **Base URL**: https://www.reb.or.kr/r-one/portal/openapi
- **주요 통계**:
- 주택가격동향조사
- 지가변동률
- 상업용부동산 임대동향
- 오피스텔 가격동향
- 공동주택 실거래가격지수
### 2.2 아파트 단지 정보 API
- **서비스명**: 한국부동산원_전국 아파트단지 정보
- **특징**: 전국 아파트 단지의 기본 정보 및 동 정보 제공
- **데이터**: 단지명, 주소, 세대수, 준공년월 등
## 3. LH 한국토지주택공사 API
### 3.1 공공임대주택 단지정보 조회 서비스
- **서비스명**: 한국토지주택공사_공공임대주택 단지정보 조회 서비스
- **URL**: https://www.data.go.kr/data/15058476/openapi.do
- **Base URL**: `apis.data.go.kr/B552555/lhPublicRentalHousingComplexInquireSvc`
- **엔드포인트**: `/getPublicRentalHousingComplexList`
- **특징**: LH에서 관리하는 공공임대주택 정보 제공
- **데이터 형식**: XML/JSON
### 3.2 임대주택단지 조회 서비스
- **서비스명**: 한국토지주택공사_임대주택단지 조회 서비스
- **URL**: https://www.data.go.kr/data/15059475/openapi.do
- **Base URL**: `apis.data.go.kr/B552555/lhLeaseholdBuldListService`
- **엔드포인트**: `/lhLeaseholdBuldList`
- **데이터**: 임대유형, 임대료, 위치 정보 등
- **데이터 형식**: XML/JSON
### 3.3 분양/임대 공고문 조회 서비스
- **서비스명**: 한국토지주택공사_분양임대공고문 조회 서비스
- **URL**: https://www.data.go.kr/data/15058530/openapi.do
- **Base URL**: `apis.data.go.kr/B552555/lhLeaseNoticeInfo`
- **엔드포인트**: `/lhLeaseNoticeInfo`
- **특징**: LH 분양/임대 공고 정보 실시간 제공
- **데이터 형식**: XML/JSON
## 4. 지자체 부동산 API
### 4.1 서울시 부동산 API
- **제공기관**: 서울특별시
- **플랫폼**: 서울 열린데이터광장 (data.seoul.go.kr)
- **주요 API**:
- 서울시 부동산 실거래가 정보
- 서울시 전월세가 정보
- 서울시 부동산 중개업소 정보
### 4.2 경기도 부동산 API
- **제공기관**: 경기도
- **플랫폼**: 경기데이터드림 (data.gg.go.kr)
- **주요 API**:
- 경기도 임대주택 현황
- 경기도 부동산 중개업소 현황
### 4.3 SH 서울주택도시공사 API
- **제공기관**: 서울주택도시공사
- **URL**: https://www.i-sh.co.kr
- **주요 데이터**:
- SH 임대주택 정보
- SH 분양 정보
- 상가 및 공장 정보
## 5. 주택금융 관련 API
### 5.1 주택도시보증공사 (HUG) API
- **제공기관**: 주택도시보증공사
- **URL**: https://www.khug.or.kr
- **Base URL**: `openapi.khug.or.kr`
- **주요 API**:
- 전세보증금 보증 정보: `/api/guarantee/deposit`
- 분양보증 정보: `/api/guarantee/sale`
- 주택금융 통계: `/api/statistics/housing`
### 5.2 마이홈포털 API
- **서비스명**: 국토교통부_마이홈포털 공공임대주택 단지정보 조회 서비스
- **URL**: https://www.data.go.kr/data/15110581/openapi.do
- **Base URL**: `apis.data.go.kr/1613000/MyHomeService`
- **엔드포인트**: `/getPublicRentalHousingInfo`
- **특징**: 전국 공공임대주택 통합 정보 제공
- **데이터 형식**: XML/JSON
## 6. Python을 이용한 API 호출 예제
### 6.1 공공데이터 API 호출 예제
```python
import requests
import xml.etree.ElementTree as ET
def get_apartment_trade_data(service_key, lawd_cd, deal_ymd):
"""
아파트 매매 실거래가 데이터 조회
"""
base_url = "http://apis.data.go.kr/1613000/RTMSDataSvcAptTrade/getRTMSDataSvcAptTrade"
params = {
'serviceKey': service_key,
'LAWD_CD': lawd_cd,
'DEAL_YMD': deal_ymd,
'pageNo': 1,
'numOfRows': 100
}
response = requests.get(base_url, params=params)
if response.status_code == 200:
# XML 파싱
root = ET.fromstring(response.content)
items = root.findall('.//item')
results = []
for item in items:
data = {
'아파트명': item.findtext('아파트'),
'전용면적': item.findtext('전용면적'),
'거래금액': item.findtext('거래금액'),
'거래년': item.findtext('년'),
'거래월': item.findtext('월'),
'거래일': item.findtext('일'),
'층': item.findtext('층'),
'건축년도': item.findtext('건축년도'),
'도로명': item.findtext('도로명'),
'법정동': item.findtext('법정동')
}
results.append(data)
return results
else:
return None
```
### 6.2 오피스텔 전월세 데이터 조회 예제
```python
def get_officetel_rent_data(service_key, lawd_cd, deal_ymd):
"""
오피스텔 전월세 실거래가 데이터 조회
"""
base_url = "http://apis.data.go.kr/1613000/RTMSDataSvcOffiRent/getRTMSDataSvcOffiRent"
params = {
'serviceKey': service_key,
'LAWD_CD': lawd_cd,
'DEAL_YMD': deal_ymd,
'pageNo': 1,
'numOfRows': 100
}
response = requests.get(base_url, params=params)
if response.status_code == 200:
root = ET.fromstring(response.content)
items = root.findall('.//item')
results = []
for item in items:
data = {
'단지명': item.findtext('단지'),
'전용면적': item.findtext('전용면적'),
'보증금': item.findtext('보증금액'),
'월세': item.findtext('월세금액'),
'층': item.findtext('층'),
'건축년도': item.findtext('건축년도'),
'법정동': item.findtext('법정동')
}
results.append(data)
return results
else:
return None
```
### 6.3 통합 API 호출 클래스 예제
```python
class RealEstateAPI:
"""
국토교통부 부동산 실거래가 통합 API 클래스
"""
BASE_URL = "http://apis.data.go.kr/1613000"
ENDPOINTS = {
'apt_trade': '/RTMSDataSvcAptTrade/getRTMSDataSvcAptTrade',
'apt_rent': '/RTMSDataSvcAptRent/getRTMSDataSvcAptRent',
'sh_trade': '/RTMSDataSvcSHTrade/getRTMSDataSvcSHTrade',
'sh_rent': '/RTMSDataSvcSHRent/getRTMSDataSvcSHRent',
'offi_trade': '/RTMSDataSvcOffiTrade/getRTMSDataSvcOffiTrade',
'offi_rent': '/RTMSDataSvcOffiRent/getRTMSDataSvcOffiRent',
'house_trade': '/RTMSDataSvcSHHouseTrade/getRTMSDataSvcSHHouseTrade',
'house_rent': '/RTMSDataSvcSHHouseRent/getRTMSDataSvcSHHouseRent',
'land': '/RTMSDataSvcLandTrade/getRTMSDataSvcLandTrade',
'business': '/RTMSDataSvcNrgTrade/getRTMSDataSvcNrgTrade'
}
def __init__(self, service_key):
self.service_key = service_key
def get_data(self, api_type, lawd_cd, deal_ymd, page=1, rows=100):
"""
통합 데이터 조회 메서드
:param api_type: API 타입 (apt_trade, apt_rent, sh_trade 등)
:param lawd_cd: 법정동 코드 5자리
:param deal_ymd: 거래년월 6자리
:param page: 페이지 번호
:param rows: 한 페이지당 행 수
"""
if api_type not in self.ENDPOINTS:
raise ValueError(f"Invalid API type: {api_type}")
url = self.BASE_URL + self.ENDPOINTS[api_type]
params = {
'serviceKey': self.service_key,
'LAWD_CD': lawd_cd,
'DEAL_YMD': deal_ymd,
'pageNo': page,
'numOfRows': rows
}
response = requests.get(url, params=params)
if response.status_code == 200:
return self._parse_xml(response.content)
else:
return None
def _parse_xml(self, xml_content):
"""XML 파싱 헬퍼 메서드"""
root = ET.fromstring(xml_content)
items = root.findall('.//item')
return [self._extract_item_data(item) for item in items]
def _extract_item_data(self, item):
"""아이템 데이터 추출"""
# XML 엘리먼트에서 모든 데이터 추출
data = {}
for child in item:
data[child.tag] = child.text
return data
```
## 7. 민간 부동산 API
### 7.1 네이버 부동산
- **특징**: 공식 API 미제공, 웹 크롤링으로 데이터 수집
- **주의사항**: robots.txt 확인 및 과도한 요청 자제
- **대안**: Selenium을 이용한 동적 페이지 크롤링
### 7.2 직방 API (비공식)
- **특징**: 내부 API 엔드포인트 활용 가능
- **주의사항**: 공식 지원 없음, 변경 가능성 있음
- **주요 엔드포인트**:
- 지역 검색: `https://apis.zigbang.com/v2/search`
- 매물 리스트: `https://apis.zigbang.com/v2/items`
- 매물 상세: `https://apis.zigbang.com/v2/items/{item_id}`
- 단지 정보: `https://apis.zigbang.com/v2/complex/{complex_id}`
### 7.3 호갱노노
- **특징**: 아파트 실거래가 정보 특화
- **URL**: https://hogangnono.com
- **데이터**: 실거래가, 시세 차트, 단지 정보
- **주의사항**: 웹 크롤링 필요
### 7.4 부동산114
- **특징**: 종합 부동산 정보 제공
- **URL**: https://www.r114.com
- **데이터**: 시세, 실거래가, 분양 정보
- **주의사항**: 회원가입 필요한 경우 있음
### 7.5 KB부동산
- **특징**: KB국민은행 제공 부동산 데이터
- **URL**: https://data.kbland.kr
- **데이터**: 주택가격동향, 시세, 통계
- **주의사항**: 일부 데이터는 유료
## 8. API 활용 시 주의사항
1. **인증키 관리**: 환경변수나 별도 설정 파일로 관리
2. **트래픽 제한**: 일일 호출 제한 확인
3. **데이터 갱신 주기**: 실시간이 아닌 일정 주기로 갱신됨
4. **에러 처리**: 네트워크 오류, 서비스 점검 대응
5. **법적 제약**: 개인정보보호법 준수
## 9. 추천 활용 방법
1. **캐싱 구현**: 동일 요청 반복 방지
2. **배치 처리**: 대량 데이터는 야간 배치로 처리
3. **데이터베이스 저장**: 조회한 데이터 로컬 DB 저장
4. **모니터링**: API 응답 시간 및 에러율 모니터링
## 10. API 종류별 요약 테이블
| 구분 | API 제공처 | 데이터 종류 | 비용 | 인증 필요 |
|------|------------|-------------|------|-----------|
| 국토교통부 | 공공데이터포털 | 아파트/오피스텔/연립/단독 실거래가 | 무료 | O |
| 한국부동산원 | 한국부동산원 | 부동산 통계, 가격지수 | 무료 | O |
| LH공사 | 공공데이터포털 | 공공임대주택 정보 | 무료 | O |
| SH공사 | SH/서울시 | 서울시 임대주택 정보 | 무료 | O |
| 지자체 | 각 지자체 | 지역별 부동산 정보 | 무료 | O |
| 네이버 | 네이버 | 매물, 시세 정보 | - | X |
| 직방 | 직방 | 원룸/오피스텔 매물 | - | X |
| 호갱노노 | 호갱노노 | 아파트 실거래가 | 무료 | X |
| 부동산114 | 부동산114 | 종합 부동산 정보 | 일부유료 | △ |
| KB부동산 | KB국민은행 | 부동산 통계/시세 | 일부유료 | △ |
## 11. API 엔드포인트 빠른 참조
### 국토교통부 실거래가 API 엔드포인트 목록
| 부동산 종류 | 거래 유형 | Base URL | 엔드포인트 |
|------------|-----------|----------|------------|
| 아파트 | 매매 | apis.data.go.kr/1613000/RTMSDataSvcAptTrade | /getRTMSDataSvcAptTrade |
| 아파트 | 전월세 | apis.data.go.kr/1613000/RTMSDataSvcAptRent | /getRTMSDataSvcAptRent |
| 연립/다세대 | 매매 | apis.data.go.kr/1613000/RTMSDataSvcSHTrade | /getRTMSDataSvcSHTrade |
| 연립/다세대 | 전월세 | apis.data.go.kr/1613000/RTMSDataSvcSHRent | /getRTMSDataSvcSHRent |
| 오피스텔 | 매매 | apis.data.go.kr/1613000/RTMSDataSvcOffiTrade | /getRTMSDataSvcOffiTrade |
| 오피스텔 | 전월세 | apis.data.go.kr/1613000/RTMSDataSvcOffiRent | /getRTMSDataSvcOffiRent |
| 단독/다가구 | 매매 | apis.data.go.kr/1613000/RTMSDataSvcSHHouseTrade | /getRTMSDataSvcSHHouseTrade |
| 단독/다가구 | 전월세 | apis.data.go.kr/1613000/RTMSDataSvcSHHouseRent | /getRTMSDataSvcSHHouseRent |
| 토지 | 매매 | apis.data.go.kr/1613000/RTMSDataSvcLandTrade | /getRTMSDataSvcLandTrade |
| 상업/업무용 | 매매 | apis.data.go.kr/1613000/RTMSDataSvcNrgTrade | /getRTMSDataSvcNrgTrade |
### 공통 파라미터
- `serviceKey`: 공공데이터포털 인증키 (필수)
- `LAWD_CD`: 법정동 코드 5자리 (필수)
- `DEAL_YMD`: 거래년월 6자리 (필수)
- `pageNo`: 페이지 번호 (선택, 기본값: 1)
- `numOfRows`: 한 페이지 결과 수 (선택, 기본값: 10)
Reference in New Issue View Git Blame Copy Permalink