건축물대장 조회를 API로 자동화하려면 정부24 화면이 아니라 공공데이터포털에서 제공하는 건축물 관련 오픈API를 이용하는 방식이 일반적이에요. 정부24는 사람이 직접 확인하고 발급받는 창구이고, 반복 조회를 프로그램으로 처리할 때는 인증키를 발급받아 호출하는 구조가 됩니다.
흔히 정부24 API라고 부르지만, 개발자가 직접 호출하는 인터페이스는 공공데이터포털의 활용신청 절차를 거쳐야 열려요. 정부24는 열람과 발급이라는 결과물에, 오픈API는 데이터를 프로그램으로 받아 쓰는 데 초점이 맞춰져 있습니다.
준비물은 생각보다 단순해요. 공공데이터포털 회원가입, 대상 서비스 활용신청, 호출에 쓸 인증키 세 가지입니다. 여기에 조회할 건물의 주소나 고유번호를 미리 목록으로 만들어 두면 작업 속도가 확실히 달라져요.
- 개발자용 호출은 공공데이터포털 활용신청 후 받은 인증키로 이루어집니다.
- 호출 한도와 반영 시간은 서비스마다 다르므로 신청 화면의 안내 값을 직접 확인해야 해요.
- 요청 파라미터 이름과 필수 여부는 기술문서의 요청 변수 표가 기준입니다.
- 소유자 관련 항목은 공개 범위 제한으로 응답에서 빠질 수 있어요.
오픈API 활용신청과 인증키 발급
공공데이터포털에 로그인한 뒤 검색창에서 건축물대장을 입력하면 관련 오픈API 목록이 나옵니다. 필요한 항목을 골라 활용신청을 누르고 활용 목적을 간단히 적으면, 심사 뒤 인증키를 확인할 수 있어요.
키를 받았다고 해서 곧바로 호출이 되는 것은 아닙니다. 발급 안내에 적힌 반영 시간이 지나야 정상 응답이 오는 경우가 있으니, 첫 테스트는 여유를 두고 진행하세요. 개발용과 운영용 키를 나눠 관리하면 실수로 운영 데이터를 건드리는 일을 줄일 수 있어요.
호출 한도는 신청 화면에 표시되는 값이 기준입니다. 하루 몇 건까지 허용되는지, 짧은 시간에 몇 번까지 보낼 수 있는지는 서비스별로 차이가 있어요. 숫자를 추측하기보다 마이페이지의 신청 내역에서 직접 확인하는 편이 정확합니다.
인증키를 소스코드에 그대로 넣거나 공개 저장소에 올리면 노출로 판단되어 사용이 중지될 수 있어요. 환경변수나 별도 설정 파일로 분리해 두고, 유출이 의심되면 재발급을 요청하세요.
요청 파라미터와 응답 형식 확인
호출은 요청 주소 뒤에 파라미터를 붙여 보내는 방식이 일반적이에요. 서비스키, 조회 대상, 페이지 위치와 개수, 응답 형식이 기본 축을 이룹니다. 조회 대상은 보통 건물 고유번호나 법정동코드와 동·호 정보로 지정해요.
파라미터 이름과 필수 여부는 서비스마다 다릅니다. 활용신청 후 받는 기술문서의 요청 변수 표를 먼저 펼쳐 보고, 필수값이 빠지면 정상 데이터 대신 오류 코드가 먼저 돌아온다는 점을 기억해 두세요.
응답은 XML과 JSON 중에서 고를 수 있는 경우가 많아요. 표제부, 층별개요, 집합건물처럼 대장 종류별로 항목이 나뉘므로, 어떤 정보가 필요한지 먼저 정한 뒤 해당 서비스를 신청하는 순서가 효율적입니다.
| 구분 | 정부24 화면 열람 | 공공데이터 오픈API |
|---|---|---|
| 주 사용 목적 | 사람이 내용을 확인 | 프로그램으로 데이터 수집 |
| 필요한 준비 | 주소 정보 | 활용신청과 인증키 |
| 결과물 | 화면 확인 또는 발급 문서 | XML·JSON 응답 데이터 |
| 반복 작업 | 건별로 직접 진행 | 한도 내에서 자동화 가능 |
정부24에서 건축물대장 조회·발급
사람이 직접 확인할 때는 정부24 검색창에 건축물대장을 입력해 메뉴로 들어간 뒤 주소를 지정하면 됩니다. 입력한 주소에 여러 건물이 걸리면 목록에서 대상을 다시 선택해야 하고, 이때 지번과 도로명주소를 함께 넣으면 정확도가 올라가요.
건축물대장 열람과 발급은 결과물이 다릅니다. 열람은 화면에서 내용을 확인하는 절차이고, 발급은 파일 형태의 문서를 받는 절차예요. 발급을 선택하면 수수료가 붙을 수 있으니 결제 전에 안내 문구를 확인하는 편이 좋습니다.
API로 받은 값과 화면 내용이 어긋날 때는 기준 시점 차이를 먼저 의심해 보세요. 갱신 주기와 대장 종류가 다르면 같은 건물이라도 표시되는 항목이 달라질 수 있습니다.
응답 오류와 트래픽 초과 대응
가장 흔한 오류는 인증키 문제예요. 키를 잘못 복사했거나, 신청하지 않은 서비스를 호출했거나, 아직 활성화 전일 때 같은 응답이 반복됩니다. 이때는 코드를 고치기 전에 신청 내역과 요청 주소를 나란히 놓고 비교해 보세요.
트래픽 초과도 자주 마주치는 항목입니다. 짧은 시간에 몰아 호출하면 한도에 걸리므로 요청 사이 간격을 두는 편이 안전해요. 같은 조건의 조회 결과는 잠시 저장해 두었다가 재사용하면 호출 횟수를 줄일 수 있습니다.
응답 형식을 JSON으로 지정해 놓고 XML 파서를 붙이면 파싱 단계에서 실패합니다. 오류 코드와 원문 응답을 함께 로그로 남겨 두면 원인을 찾는 시간이 크게 줄어요.
재시도는 간격을 늘려가며 2~3회만 시도하는 편이 좋아요. 같은 요청을 즉시 반복하면 남은 한도만 소모되고, 성공 응답을 받은 뒤에는 결과를 저장해 두는 습관이 트래픽 관리에 도움이 됩니다.
건축물 정보 조회 결과 검증
받은 데이터를 그대로 쓰기 전에 대장 종류를 확인하세요. 일반건축물대장과 집합건물대장은 담는 항목이 달라서 같은 주소라도 특정 필드가 비어 있을 수 있어요. 서비스 설명에 적힌 대상 대장을 먼저 읽으면 이런 혼동을 줄일 수 있습니다.
폐쇄말소된 대장이나 주소가 변경된 건물은 결과가 비어 보일 수 있습니다. 도로명주소와 지번주소를 각각 넣어 호출해 보고, 그래도 값이 없으면 관할 지자체에 확인하는 편이 정확해요. 공공데이터 활용에서는 원본 대장과 대조하는 검증 단계를 두는 것이 안전합니다.
소유자 관련 항목은 공개 범위가 제한되는 경우가 있어요. 개인정보가 걸린 필드는 응답에서 빠지거나 일부가 가려질 수 있으니, 필요한 정보가 무엇인지 먼저 정하고 기술문서의 제공 항목과 하나씩 맞춰 보세요.
자주 묻는 질문
Q. 정부24에서 API 키를 바로 발급받을 수 있나요?
A. 정부24는 열람과 발급을 처리하는 화면 기반 서비스이고, 개발자용 호출은 공공데이터포털에서 활용신청을 거쳐야 합니다. 정부24 API라는 표현을 쓰더라도 실제 키 발급 창구는 별도라는 점을 구분해 두세요.
Q. 인증키를 받으면 바로 호출이 되나요?
A. 발급 직후에는 반영 대기 시간이 있어 오류가 돌아올 수 있습니다. 안내된 시간이 지난 뒤에도 같은 오류가 나오면 신청한 서비스명과 요청 주소가 일치하는지부터 확인하세요.
Q. 소유자 이름까지 API로 받을 수 있나요?
A. 소유자 관련 항목은 개인정보 보호 기준에 따라 제공 범위가 제한될 수 있습니다. 응답 필드가 비어 있다면 오류가 아니라 제공 항목에서 빠진 것일 수 있으니 기술문서의 항목 설명을 확인해 보세요.
Q. 하루 호출 한도는 얼마인가요?
A. 한도는 서비스와 신청 유형에 따라 달라서 하나의 숫자로 말하기 어렵습니다. 활용신청 화면과 마이페이지 신청 내역에 표시되는 값을 기준으로 삼고, 운영 환경에서는 그보다 여유를 두고 설계하세요.
Q. 조회 결과를 서비스에 그대로 써도 되나요?
A. 공공데이터라도 이용 조건과 출처 표시 기준이 정해져 있으므로 활용신청 시 안내된 약관을 확인해야 합니다. 상업적 목적으로 쓸 계획이라면 배포 전에 이용 허용 범위를 별도로 확인하는 절차를 두세요.
정리하면, 건축물대장 조회를 프로그램으로 처리할 때의 출발점은 공공데이터포털 활용신청과 인증키 확보입니다. 그다음 기술문서의 요청 변수와 응답 항목을 확인하고, 한도 안에서 재시도와 저장을 조합하면 안정적으로 운영할 수 있어요.
사람이 확인만 하면 되는 상황이라면 정부24 화면으로 충분합니다. 자동화가 필요한지, 소유자 정보까지 필요한지에 따라 경로를 나눠 선택하는 것이 불필요한 시행착오를 줄이는 방법입니다.
이 글은 일반적인 정보 제공을 목적으로 작성되었습니다. 세부 기준과 적용 조건은 개정 여부나 개인의 상황에 따라 달라질 수 있으므로, 실제 결정을 내리기 전에 관련 기관의 최신 안내나 해당 분야 전문가의 확인을 받으시길 권장합니다.
