국토교통부 아파트 매매 실거래가 자료 API 데이터 연계

1. 개요

국토교통부에서 제공하는 “아파트 매매 실거래가 상세자료 OpenAPI”는 전국 아파트 실거래 신고 데이터를 조회할 수 있는 공공데이터 API입니다.

해당 API를 활용하면 아래와 같은 기능 구현이 가능합니다.

• 지역별 아파트 실거래 조회
• 월별 거래 내역 분석
• 실거래가 통계 서비스 구축
• 부동산 시세 분석 플랫폼 개발
• 아파트 거래 이력 조회
• 실거래 데이터 수집 자동화

제공 기관은 국토교통부 및 한국부동산원 입니다.

---

2. data.go.kr 활용 신청 방법

2-1. 공공데이터포털 접속

공공데이터포털 접속

공공데이터포털

---

2-2. 회원가입 및 로그인

• 회원가입 진행
• 로그인 수행
• 일반회원 또는 기업회원 선택 가능

---

2-3. API 검색

검색창에 아래 키워드 입력

아파트 매매 실거래가 상세자료

또는 아래 서비스 검색

• 서비스명:
  아파트 매매 실거래가 상세자료

---

2-4. 활용 신청

API 페이지에서 다음 절차 수행

1. 활용신청 클릭
2. 활용 목적 입력
3. 개발계정 신청
4. 승인 대기

일반적으로 승인까지 수 시간 ~ 2일 정도 소요됩니다.

---

2-5. 인증키(ServiceKey) 발급

승인 완료 후 아래 정보 확인 가능

• 일반 인증키
• URL Encoding 인증키

실제 API 호출 시에는 URL Encoding 된 인증키 사용을 권장합니다.

---

3. API 기본 정보

API명	아파트 매매 실거래가 상세자료
방식	REST(GET)
응답포맷	XML
데이터 갱신	일 1회
서비스URL	http://apis.data.go.kr/1613000/RTMSDataSvcAptTradeDev
상세기능	getRTMSDataSvcAptTradeDev

---

4. API 호출 URL 구조

기본 URL

http://apis.data.go.kr/1613000/RTMSDataSvcAptTradeDev/getRTMSDataSvcAptTradeDev

---

전체 요청 예시

http://apis.data.go.kr/1613000/RTMSDataSvcAptTradeDev/getRTMSDataSvcAptTradeDev
?serviceKey=발급키
&LAWD_CD=11110
&DEAL_YMD=202407
&pageNo=1
&numOfRows=10

---

5. Request Parameter 상세 설명

5-1. 전체 Request Parameter 정리

파라미터타입필수여부설명예시

serviceKey	String	필수	공공데이터포털 발급 인증키	인증키값
LAWD_CD	String(5)	필수	지역코드(법정동코드 앞 5자리)	11110
DEAL_YMD	String(6)	필수	계약년월	202407
pageNo	Integer	선택	페이지 번호	1
numOfRows	Integer	선택	페이지당 건수	10

---

6. 지역코드(LAWD_CD) 설명

지역코드는 법정동 코드 기준입니다.

주요 지역코드 예시

서울 종로구	11110
서울 강남구	11680
서울 송파구	11710
부산 해운대구	26350
대구 수성구	27260
인천 연수구	28185

법정동코드 조회:

법정동코드 조회 시스템

---

7. DEAL_YMD 설명

계약년월 정보입니다.

형식:

YYYYMM

예시:

값의미

202401	2024년 1월
202407	2024년 7월
202512	2025년 12월

---

8. Java 연계 예제

8-1. HttpURLConnection 방식

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
import java.net.URLEncoder;

public class AptTradeApiExample {

    public static void main(String[] args) throws Exception {

        String serviceKey = "발급받은인증키";

        StringBuilder urlBuilder = new StringBuilder(
            "http://apis.data.go.kr/1613000/RTMSDataSvcAptTradeDev/getRTMSDataSvcAptTradeDev"
        );

        urlBuilder.append("?" + URLEncoder.encode("serviceKey", "UTF-8")
                + "=" + URLEncoder.encode(serviceKey, "UTF-8"));

        urlBuilder.append("&" + URLEncoder.encode("LAWD_CD", "UTF-8")
                + "=" + URLEncoder.encode("11110", "UTF-8"));

        urlBuilder.append("&" + URLEncoder.encode("DEAL_YMD", "UTF-8")
                + "=" + URLEncoder.encode("202407", "UTF-8"));

        urlBuilder.append("&" + URLEncoder.encode("pageNo", "UTF-8")
                + "=" + URLEncoder.encode("1", "UTF-8"));

        urlBuilder.append("&" + URLEncoder.encode("numOfRows", "UTF-8")
                + "=" + URLEncoder.encode("10", "UTF-8"));

        URL url = new URL(urlBuilder.toString());

        HttpURLConnection conn =
                (HttpURLConnection) url.openConnection();

        conn.setRequestMethod("GET");
        conn.setRequestProperty("Content-type", "application/xml");

        System.out.println("Response Code : " + conn.getResponseCode());

        BufferedReader rd;

        if(conn.getResponseCode() >= 200 &&
                conn.getResponseCode() <= 300) {

            rd = new BufferedReader(
                    new InputStreamReader(conn.getInputStream()));
        } else {

            rd = new BufferedReader(
                    new InputStreamReader(conn.getErrorStream()));
        }

        StringBuilder sb = new StringBuilder();
        String line;

        while((line = rd.readLine()) != null) {
            sb.append(line);
        }

        rd.close();
        conn.disconnect();

        System.out.println(sb.toString());
    }
}

---

반응형

9. Python 연계 예제

9-1. requests 라이브러리 사용

import requests

SERVICE_KEY = "발급받은인증키"

url = "http://apis.data.go.kr/1613000/RTMSDataSvcAptTradeDev/getRTMSDataSvcAptTradeDev"

params = {
    "serviceKey": SERVICE_KEY,
    "LAWD_CD": "11110",
    "DEAL_YMD": "202407",
    "pageNo": "1",
    "numOfRows": "10"
}

response = requests.get(url, params=params)

print("상태코드:", response.status_code)
print(response.text)

---

10. Python XML Parsing 예제

import requests
import xml.etree.ElementTree as ET

SERVICE_KEY = "발급받은인증키"

url = "http://apis.data.go.kr/1613000/RTMSDataSvcAptTradeDev/getRTMSDataSvcAptTradeDev"

params = {
    "serviceKey": SERVICE_KEY,
    "LAWD_CD": "11110",
    "DEAL_YMD": "202407",
    "pageNo": "1",
    "numOfRows": "10"
}

response = requests.get(url, params=params)

root = ET.fromstring(response.text)

items = root.findall(".//item")

for item in items:

    aptNm = item.findtext("aptNm")
    dealAmount = item.findtext("dealAmount")
    buildYear = item.findtext("buildYear")
    floor = item.findtext("floor")

    print("아파트명 :", aptNm)
    print("거래금액 :", dealAmount)
    print("건축년도 :", buildYear)
    print("층 :", floor)
    print("--------------------------------")

---

11. Java XML Parsing 예제

import org.w3c.dom.*;
import javax.xml.parsers.*;
import java.io.InputStream;
import java.net.URL;

public class XmlParsingExample {

    public static void main(String[] args) throws Exception {

        String apiUrl =
            "http://apis.data.go.kr/1613000/RTMSDataSvcAptTradeDev/getRTMSDataSvcAptTradeDev"
            + "?serviceKey=인증키"
            + "&LAWD_CD=11110"
            + "&DEAL_YMD=202407";

        URL url = new URL(apiUrl);

        InputStream is = url.openStream();

        DocumentBuilderFactory dbFactory =
                DocumentBuilderFactory.newInstance();

        DocumentBuilder dBuilder =
                dbFactory.newDocumentBuilder();

        Document doc = dBuilder.parse(is);

        doc.getDocumentElement().normalize();

        NodeList nodeList = doc.getElementsByTagName("item");

        for (int i = 0; i < nodeList.getLength(); i++) {

            Node node = nodeList.item(i);

            if(node.getNodeType() == Node.ELEMENT_NODE) {

                Element element = (Element) node;

                String aptNm =
                        element.getElementsByTagName("aptNm")
                                .item(0)
                                .getTextContent();

                String dealAmount =
                        element.getElementsByTagName("dealAmount")
                                .item(0)
                                .getTextContent();

                System.out.println("아파트명 : " + aptNm);
                System.out.println("거래금액 : " + dealAmount);
            }
        }
    }
}

---

12. 응답(Response) 구조 상세 설명

전체 XML 구조

<response>
    <header>
        <resultCode>000</resultCode>
        <resultMsg>OK</resultMsg>
    </header>

    <body>
        <items>
            <item>
                ...
            </item>
        </items>

        <numOfRows>10</numOfRows>
        <pageNo>1</pageNo>
        <totalCount>40</totalCount>
    </body>
</response>

---

13. 응답값(item) 상세 설명

필드명설명

aptNm	아파트명
dealAmount	거래금액(만원)
excluUseAr	전용면적
floor	층
buildYear	건축년도
dealYear	계약년도
dealMonth	계약월
dealDay	계약일
jibun	지번
roadNm	도로명
dealingGbn	거래유형
estateAgentSggNm	중개사 소재지
buyerGbn	매수자 유형
slerGbn	매도자 유형
aptDong	동 정보
rgstDate	등기일자
landLeaseholdGbn	토지임대부 여부

---

14. 실제 응답 예시

<item>
    <aptDong></aptDong>
    <aptNm>종로중흥S클래스</aptNm>
    <aptSeq>11110-2339</aptSeq>
    <bonbun>0202</bonbun>
    <bubun>0003</bubun>
    <buildYear>2013</buildYear>
    <buyerGbn>개인</buyerGbn>
    <dealAmount>12,000</dealAmount>
    <dealDay>23</dealDay>
    <dealMonth>7</dealMonth>
    <dealYear>2024</dealYear>
    <dealingGbn>중개거래</dealingGbn>
    <estateAgentSggNm>서울 종로구</estateAgentSggNm>
    <excluUseAr>17.811</excluUseAr>
    <floor>10</floor>
    <jibun>202-3</jibun>
    <landLeaseholdGbn>N</landLeaseholdGbn>
    <roadNm>종로66길</roadNm>
    <sggCd>11110</sggCd>
    <umdNm>숭인동</umdNm>
</item>

---

15. 응답 데이터 의미 해석

예시 데이터:

아파트명	종로중흥S클래스
거래금액	1억 2천만원
전용면적	17.811㎡
층수	10층
거래방식	중개거래
거래일	2024-07-23

---

16. 페이징 처리 방법

데이터가 많을 경우 페이지 단위 조회 필요

예시:

&pageNo=1&numOfRows=100
&pageNo=2&numOfRows=100
&pageNo=3&numOfRows=100

 

17. 에러코드 상세 설명

000	정상
01	Application Error
02	DB Error
03	No Data
04	HTTP Error
05	Service Timeout
10	잘못된 요청 파라미터
11	필수 요청 파라미터 누락
20	서비스 접근 거부
22	요청 제한 초과
30	등록되지 않은 서비스키
31	기간 만료된 서비스키
32	등록되지 않은 IP/도메인

---

18. API 연계 시 자주 발생하는 문제

인증키 인코딩 문제

잘못된 예:

serviceKey=abcd+/=

정상 예:

serviceKey=abcd%2B%2F%3D

---

XML 파싱 오류

원인:

• 특수문자 처리
• 인코딩 문제
• 응답 비정상

해결:

conn.setRequestProperty("Content-type", "application/xml;charset=UTF-8");

 

#공공데이터API
#data.go.kr
#실거래가API
#아파트실거래가
#국토교통부API
#부동산API
#OpenAPI연동
#JavaAPI연동
#PythonAPI연동
#RESTAPI
#XML파싱
#부동산데이터
#실거래가조회
#아파트매매API
#공공데이터포털
#SpringBootAPI
#PythonRequests
#부동산플랫폼
#실거래가수집
#부동산개발