이 API는 2024년 서울AI 허브-마이크로소프트(MS) 공동교육을 위해 제작된 교육용 API입니다. 서울시의 부동산 실거래가 정보를 제공하며, API 문서 읽는 법과 API 사용 방법을 학습하는 데 활용됩니다.
API 문서를 읽을 때 다음 사항들을 주의 깊게 살펴보세요:
GET https://hysis-notice-compare.azurewebsites.net/api/seoulrealestatetransactionsfunction
| 파라미터 | 설명 | 필수 여부 |
|---|---|---|
| bjdong_cd | 법정동 코드 (5자리 문자열) | 필수 |
| bldg_nm | 건물명 | 필수 |
| x-api-key | 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" |
아래의 Swagger UI를 사용하여 API를 직접 테스트해볼 수 있습니다. 사용 방법은 다음과 같습니다:
주의: API 키는 개인정보이므로 공유하거나 노출되지 않도록 주의하세요.
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 -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"
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": "서울 강남구"
}
]