사업장 건물 실거래 - 공공데이터 기업 위험 조회

1. 사업장 건물 실거래 조회opendata.nrg.trades

MCP 도구 이름 opendata__nrg__trades

POSThttps://api.xdata.kr/v1/jobsX-Env-Scope: real_test

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

사업장 주소 또는 사업자등록번호로 그 지번의 상업용 및 업무용 부동산 매매 실거래(계약일, 거래금액, 건물 주용도, 면적, 층, 거래유형, 해제 여부)를 최근 기간만큼 조회합니다.

Request

변수명	필수	설명
Authorization	Y	API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. 형식 : Basic base64("{client_id}:{client_secret}") [참고] 인증
X-Env-Scope	Y	호출 환경입니다. `real_test`데모 — 현재 데모 한도 확인 필요 `production`정식 — 현재 공개 요금제 전용 [참고] 환경
Idempotency-Key	Y	재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. [참고] 재시도
Content-Type	Y	요청 본문 형식입니다. `application/json`고정값 (기본값)
X-Trace-Id	N	추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.

변수명	타입	필수	설명
provider	string	Y	호출할 기관입니다. `opendata`이 API 고정값 (기본값) 예시 : opendata
action	string	Y	호출할 작업입니다. `opendata.nrg.trades`이 API 고정값 (기본값) 예시 : opendata.nrg.trades
params	object	Y	작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fields	object	N	민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. [참고] 암호화

변수명	타입	길이	필수	설명
address	string	-	N	사업장 주소(도로명 또는 지번, 건물번호까지). address 와 bizno 가운데 하나 이상
bizno	string	-	N	사업자등록번호 10자리(하이픈 허용). address 가 없을 때 등록된 소재지를 찾는 데 씁니다
months	number	-	N	조회 기간(개월, 선택, 기본 12). endYm 부터 거슬러 셉니다
endYm	string	6	N	조회 기간의 끝 달(선택, 기본 이번 달) 형식 : YYYYMM
output_formats	array	-	N	이 결과를 엑셀(xlsx) 파일로도 받으려면 적습니다. 예: ["xlsx"]. 파일은 result.artifacts 에 함께 오고, 빼면 데이터만 옵니다

bash

curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: real_test' \
  --header 'Idempotency-Key: demo-trades-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "opendata",
  "action": "opendata.nrg.trades",
  "params": {}
}'

Response

아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
이 API 가 돌려주는 데이터: 시군구, 법정동, 지번, 유형, 건물 주용도, 용도지역, 건축년도, 건물면적, 대지면적, 층, 계약 연도와 월과 일, 거래금액, 거래유형, 해제여부, 해제사유 발생일, 매수자 구분, 매도자 구분

변수명	타입	설명
source_id	string	이 작업의 원천 데이터셋 번호입니다. 이 작업에서는 항상 15126463 입니다(공공데이터포털 data.go.kr 의 번호).
action	string	호출한 작업 이름입니다. 이 작업에서는 항상 opendata.nrg.trades 입니다.
job_id	string	이 결과를 만든 작업의 ID 입니다.
source	object	원천의 출처 정보입니다. 결과를 사용자에게 보여 줄 때 출처 표시에 씁니다.
source.id	string	원천 데이터셋 번호입니다. source_id 와 같은 값입니다.
source.org	string	원천 데이터를 제공하는 기관 이름입니다. 이 작업에서는 항상 국토교통부 입니다.
source.license	string	원천 데이터의 이용 허락 범위 표기입니다. 값은 원천마다 다르고, 결과를 보여 줄 때 출처 표시와 함께 씁니다.
license_notes	array	출처 표시 문구, 이용 허락 표기, 결과 해석 안내가 이 순서로 담긴 문장 목록입니다. 첫 줄은 「출처: 국토교통부 상업업무용 부동산 매매 실거래가 / data.go.kr 15126463」 입니다.
upstream	object	상업용 및 업무용 부동산 매매 실거래를 주소의 지번과 기간으로 찾은 결과입니다. 거래는 원천을 그때그때 부르지 않고 미리 받아 둔 자료에서 찾습니다. 조회 기간의 달 가운데 받아 둔 달이 하나도 없으면 이 결과를 만들지 않고, 조회에 쓸 자료가 아직 준비되지 않았다는 오류로 끝납니다. 아래 칸은 우리가 정해 담습니다.
upstream.source_op	string	원천에서 부른 조회 이름입니다. 이 작업에서는 항상 getRTMSDataSvcNrgTrade 입니다.
upstream.address	object	주소 검색 단계의 결과입니다. keyword(입력한 주소 글자), chosen(고른 첫 번째 후보), candidates(주소 검색 후보 목록), total_count(검색된 후보 전체 수)가 담깁니다. 후보가 여럿이면 첫 번째 후보의 지번으로 조회하므로 candidates 를 확인해 주세요.
upstream.lot	object \| null	조회에 쓴 지번 키입니다. sigunguCd(시군구 코드), bjdongCd(법정동 코드), bun(본번), ji(부번)가 담깁니다. 주소를 지번에 맞추지 못했으면 null 이고 이때 거래를 찾지 않습니다.
upstream.period	object	조회한 기간입니다. 끝 달(요청한 endYm, 비우면 이번 달)부터 거슬러 올라간 months 개월입니다.
upstream.period.start_ym	string	조회 기간의 첫 달(YYYYMM)입니다.
upstream.period.end_ym	string	조회 기간의 마지막 달(YYYYMM)입니다.
upstream.period.months	number	조회 기간의 개월 수입니다.
upstream.coverage	object	미리 받아 둔 자료가 조회 기간을 얼마나 덮는지입니다.
upstream.coverage.requested_months	array	조회 기간의 모든 달 목록(YYYYMM, 오름차순)입니다.
upstream.coverage.covered_months	array	requested_months 가운데 거래 자료를 받아 둔 달의 목록입니다.
upstream.coverage.missing_months	array	받아 두지 않아 거래를 찾지 못한 달의 목록입니다. 이 달의 거래는 결과에 없으며 거래가 없다는 뜻이 아닙니다. 주소를 지번에 맞추지 못해 자료를 읽지 않았으면 빈 목록입니다.
upstream.coverage.unresolved_dong_rows	number	받아 둔 자료 가운데 법정동을 확인하지 못해 지번 비교에서 빠진 행의 수입니다. 0 이 아니면 그만큼의 행에 같은 지번의 거래가 있었더라도 결과에 없습니다.
upstream.trades	array	같은 지번의 거래 행 목록입니다. 지번이 글자 그대로 같은 거래가 먼저 오고 지번 일부가 가려진 거래(1** 꼴)가 뒤에 오며, 각각 최근 계약일이 앞입니다. 해제된 거래도 담기고 해제 여부 칸(cdealType)이 O 이면 해제된 거래입니다. 안쪽 칸은 원천이 정하므로 이 문서가 칸 하나하나를 보장하지 않습니다. 비어 있으면 받아 둔 기간에 그 지번의 거래를 찾지 못했다는 뜻이며 거래가 없다는 확인서는 아닙니다.
upstream.summary	object	거래 요약입니다.
upstream.summary.trades	number	trades 목록의 거래 수입니다.
upstream.summary.exact_jibun	number	지번이 글자 그대로 같은 거래의 수입니다.
upstream.summary.masked_jibun	number	지번 일부가 가려졌지만 보이는 자리가 맞아 같은 지번일 수 있는 거래의 수입니다. 지번 열을 확인해 주세요.
upstream.summary.cancelled	number	해제된 거래의 수입니다. trades 에는 포함됩니다.
upstream.summary.latest_deal_ym	string \| null	거래 가운데 가장 최근 계약 연월(YYYYMM)입니다. 거래가 없으면 null 입니다.
upstream.summary.amount_manwon	object \| null	해제되지 않은 거래의 거래금액 범위(만원 단위)입니다. min(가장 작은 금액)과 max(가장 큰 금액)가 담기고, 해제되지 않은 거래가 없으면 null 입니다.
upstream.total_count	number	trades 목록의 거래 수입니다.
upstream.coverage_note	string	이 조회의 범위와 한계를 알리는 안내문입니다. 받아 두지 않은 달의 거래는 결과에 없다는 점, 지번 일부가 가려진 거래가 섞일 수 있다는 점, 비어 있는 결과가 거래가 없다는 확인서가 아니라는 점을 적습니다. 주소를 지번에 맞추지 못했으면 그 사실과 다시 요청하는 방법을 적습니다.
upstream.resolution	object	사업자등록번호만 보내 조회 주소를 찾아 쓴 경우에만 오는 해소 결과입니다. address 를 직접 보냈으면 이 칸이 없습니다.
upstream.resolution.address	string \| null	번호로 찾아 조회에 쓴 사업장 주소입니다.

json

{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "real_test",
    "provider": "opendata",
    "action": "opendata.nrg.trades",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}

순번	오류 코드	발생 조건
	POLICY_QUOTA_EXCEEDED	공공데이터 조회의 하루 한도를 모두 쓰면 작업이 이 오류로 끝납니다. error.message 는 「오늘 이 조직의 공공데이터 조회 한도를 모두 썼습니다. 한국시간 자정에 다시 열립니다. 한도 상향이 필요하면 서비스문의로 알려 주세요.」 꼴이고, 한도의 범위에 따라 「이 조직의」 대신 「무료 요금제 몫의」 나 「서비스 전체」 가 들어갑니다. 자정이 지난 뒤에 다시 요청합니다.
	PROVIDER_UPSTREAM_ERROR	공공데이터 제공처가 오류로 답하면 작업이 이 오류로 끝나고, error.message 는 응답 상태로 고릅니다. 429 이면 「요청이 잠시 제한되었습니다. 잠시 후 다시 시도해 주세요.」, 403 이면 「요청하신 자료를 조회할 권한이 없습니다. 연동한 계정에 그 권한이 있는지 확인해 주세요.」, 500번대이면 「일시적인 오류로 요청을 마치지 못했습니다. 잠시 후 다시 시도해 주세요.」, 그 밖의 400번대이면 「요청을 처리할 수 없습니다. 입력한 값을 다시 확인해 주세요.」 입니다. 응답은 받았는데 읽지 못했거나 상태를 알 수 없으면 「기관에서 받은 응답을 처리하지 못했습니다. 잠시 후 다시 시도해 주시고, 계속되면 서비스문의로 알려 주세요.」 가 오고, 상태가 400번대도 500번대도 아니면 「서버 내부 오류로 작업을 마치지 못했습니다. 잠시 후 다시 시도해 주세요.」 가 옵니다.
	VALIDATION_INVALID_FIELD	요청 값이 맞지 않으면 작업이 이 오류로 끝나고, 요청을 고쳐 다시 보냅니다. 값이 빠지면 error.message 는 「요청에 필요한 값이 빠졌습니다. 빠진 값: 칸 이름. 그 값을 넣어 다시 요청해 주세요.」 꼴이고, 값의 형식이 틀리면 「요청 값이 올바르지 않습니다. 확인할 값: 칸 이름. 값을 고쳐 다시 요청해 주세요.」 꼴입니다(칸 이름이 다섯을 넘으면 앞 다섯과 「외 N개」 를 적습니다). 사업자등록번호 칸이면 「사업자등록번호는 숫자 열 자리로 보내 주세요.」 가 옵니다. 지원하지 않는 작업을 부르면 「지원하지 않는 작업입니다.」 입니다.
	INTERNAL_ERROR	우리 쪽 설정이나 처리 결함으로 끝나면 이 오류가 나가고 error.message 는 「서버 내부 오류로 작업을 마치지 못했습니다. 잠시 후 다시 시도해 주세요.」 입니다. 고객이 고칠 값이 없으므로 잠시 뒤 다시 요청하고, 계속되면 서비스문의로 알려 주세요.