서울시 부동산 실거래가 정보 API (교육용)

API 소개

이 API는 2024년 서울AI 허브-마이크로소프트(MS) 공동교육을 위해 제작된 교육용 API입니다. 서울시의 부동산 실거래가 정보를 제공하며, API 문서 읽는 법과 API 사용 방법을 학습하는 데 활용됩니다.

API 문서 읽는 법

API 문서를 읽을 때 다음 사항들을 주의 깊게 살펴보세요:

OpenAPI JSON 다운로드

파워 오토메이트 사용자 지정 커넥터에 사용할 수 있는 OpenAPI JSON 파일을 다운로드하세요:

OpenAPI JSON 다운로드

법정동코드 샘플 다운로드

API 사용 시 필요한 법정동코드 샘플 데이터를 다운로드하세요:

법정동코드 샘플 다운로드 (Excel)

요청 URL

GET https://hysis-notice-compare.azurewebsites.net/api/seoulrealestatetransactionsfunction

요청 파라미터 설명

파라미터 설명 필수 여부
bjdong_cd 법정동 코드 (5자리 문자열) 필수
bldg_nm 건물명 필수
x-api-key API 인증 키 (헤더에 포함) 필수

API 키 보안

API 키는 민감한 정보이므로 안전하게 관리해야 합니다:

응답 형식 설명

응답은 JSON 배열 형태로 제공되며, 각 객체는 다음과 같은 속성을 가집니다:

필드 설명 예시 값
ACC_YEAR 접수연도: 거래가 접수된 연도 "2024"
SGG_CD 자치구코드: 해당 부동산이 위치한 자치구의 코드 "11740" (강동구)
SGG_NM 자치구명: 해당 부동산이 위치한 자치구의 이름 "강동구"
BJDONG_CD 법정동코드: 해당 부동산이 위치한 법정동의 코드 "10800" (성내동)
BJDONG_NM 법정동명: 해당 부동산이 위치한 법정동의 이름 "성내동"
LAND_GBN 지번구분: 1(대지), 2(산), 3(블럭) "1" (대지)
LAND_GBN_NM 지번구분명: 지번구분에 대한 설명 "대지"
BONBEON 본번: 부동산의 지번 중 본번 "0459"
BUBEON 부번: 부동산의 지번 중 부번 "0009"
BLDG_NM 건물명: 해당 부동산의 이름 "삼성파크타워"
DEAL_YMD 계약일자: 거래가 이루어진 날짜 (YYYYMMDD 형식) "20240613" (2024년 6월 13일)
OBJ_AMT 물건금액: 거래 금액 (만원 단위) "215000" (2억 1500만원)
BLDG_AREA 건물면적: 건물의 면적 (제곱미터) 216.08 (약 65.36평)
TOT_AREA 토지면적: 토지의 총 면적 (제곱미터) 0.0 (정보 없음)
FLOOR 층: 해당 거래 물건의 층수 3.0 (3층)
RIGHT_GBN 권리구분: 소유권에 대한 권리 정보 "" (정보 없음)
CNTL_YMD 취소일자: 거래가 취소된 경우 그 날짜 (YYYYMMDD 형식) "" (취소되지 않음)
BUILD_YEAR 건축년도: 건물이 지어진 년도 "1995"
HOUSE_TYPE 건물용도: 건물의 사용 목적 "아파트"
REQ_GBN 신고구분: 거래의 신고 유형 "중개거래"
RDEALER_LAWDNM 신고한 개업공인중개사 시군구명: 거래를 신고한 중개사의 소재지 "서울 강남구"

에러 코드

코드 설명 메시지
400 잘못된 요청 (필수 파라미터 누락 등) "Please provide bjdong_cd, and bldg_nm in the query parameters."
401 인증 실패 (잘못된 API 키) "Unauthorized: Invalid API Key"
500 서버 오류 "Error occurred while fetching data: [구체적인 오류 메시지]" 또는 "Unexpected response format from the API"

API 테스트 (Swagger UI)

아래의 Swagger UI를 사용하여 API를 직접 테스트해볼 수 있습니다. 사용 방법은 다음과 같습니다:

  1. 엔드포인트 선택: GET /seoulrealestatetransactionsfunction을 클릭하여 펼칩니다.
  2. Try it out 버튼 클릭: 우측의 "Try it out" 버튼을 클릭하여 테스트 모드로 전환합니다.
  3. 파라미터 입력:
    • bjdong_cd: 법정동 코드 5자리 (예: "10800")
    • bldg_nm: 조회할 건물 이름 (예: "삼성파크타워")
    • x-api-key: 제공받은 API 키를 입력합니다.
  4. Execute 버튼 클릭: 입력을 마치면 파란색 "Execute" 버튼을 클릭하여 API를 호출합니다.
  5. 응답 확인:
    • Responses 섹션에서 서버 응답 코드를 확인합니다.
    • Response body에서 반환된 JSON 데이터를 확인합니다.
    • 에러 발생 시 Response headers와 Response body를 통해 오류 정보를 확인합니다.

주의: API 키는 개인정보이므로 공유하거나 노출되지 않도록 주의하세요.

API 사용 예시

Python


import requests
import json

# 테스트 파라미터 설정
params = {
    "bjdong_cd": "10800",  # 법정동 코드
    "bldg_nm": "삼성파크타워"  # 건물명
}

# 애저 펑션 엔드포인트 URL 설정
function_url = "https://hysis-notice-compare.azurewebsites.net/api/seoulrealestatetransactionsfunction"

# 요청 헤더에 API 키 추가
headers = {
    "x-api-key": "Quxh0wbaFcK3aTQW5VTWQGKxac3kbv-8bAISsSlOEJQ0AzFu1URfsA==",  # API 키
    "Content-Type": "application/json"
}

try:
    # GET 요청 보내기
    response = requests.get(function_url, headers=headers, params=params)
    
    # 상태 코드 확인
    if response.status_code == 200:
        # 응답 JSON 데이터 파싱 및 출력
        data = response.json()
        print("응답 데이터:")
        print(json.dumps(data, indent=2, ensure_ascii=False))  # 한글 깨짐 방지 및 들여쓰기 적용
        
        # 데이터 분석 예시 (첫 번째 항목의 일부 정보 출력)
        if data and len(data) > 0:
            first_item = data[0]
            print(f"\n건물명: {first_item['BLDG_NM']}")
            print(f"거래 금액: {first_item['OBJ_AMT']}만원")
            print(f"거래 일자: {first_item['DEAL_YMD']}")
    elif response.status_code == 400:
        print("에러: 잘못된 요청입니다. 파라미터를 확인해주세요.")
    elif response.status_code == 401:
        print("에러: 인증에 실패했습니다. API 키를 확인해주세요.")
    else:
        print(f"에러: {response.status_code} - {response.text}")

except requests.RequestException as e:
    print(f"요청 중 오류가 발생했습니다: {str(e)}")
except json.JSONDecodeError:
    print("응답을 JSON으로 파싱하는 데 실패했습니다.")
except Exception as e:
    print(f"예상치 못한 오류가 발생했습니다: {str(e)}")
                

cURL


curl -X GET "https://hysis-notice-compare.azurewebsites.net/api/seoulrealestatetransactionsfunction?bjdong_cd=10800&bldg_nm=삼성파크타워" \
     -H "x-api-key: Quxh0wbaFcK3aTQW5VTWQGKxac3kbv-8bAISsSlOEJQ0AzFu1URfsA=" \
     -H "Content-Type: application/json"
                

Java


import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class ApiExample {
    public static void main(String[] args) throws Exception {
        String url = "https://hysis-notice-compare.azurewebsites.net/api/seoulrealestatetransactionsfunction?bjdong_cd=10800&bldg_nm=삼성파크타워";
        
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(url))
                .header("x-api-key", "Quxh0wbaFcK3aTQW5VTWQGKxac3kbv-8bAISsSlOEJQ0AzFu1URfsA=")
                .header("Content-Type", "application/json")
                .GET()
                .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}
                

응답 예시


[
  {
    "ACC_YEAR": "2024",
    "SGG_CD": "11740",
    "SGG_NM": "강동구",
    "BJDONG_CD": "10800",
    "BJDONG_NM": "성내동",
    "LAND_GBN": "1",
    "LAND_GBN_NM": "대지",
    "BONBEON": "0459",
    "BUBEON": "0009",
    "BLDG_NM": "삼성파크타워",
    "DEAL_YMD": "20240613",
    "OBJ_AMT": "215000",
    "BLDG_AREA": 216.08,
    "TOT_AREA": 0.0,
    "FLOOR": 3.0,
    "RIGHT_GBN": "",
    "CNTL_YMD": "",
    "BUILD_YEAR": "1995",
    "HOUSE_TYPE": "아파트",
    "REQ_GBN": "중개거래",
    "RDEALER_LAWDNM": "서울 강남구"
  }
]