API Client 구현 대상은 DOCX의 AptIdInfoSvc 3개 오퍼레이션이다. XLSX는 직접 호출 가능한 API 명세라기보다 국가중점데이터 컬럼정의서/코드표로 보이며, ZIP:ON의 향후 공간정보·토지·공시가격·중개업 데이터 모델 설계 부록으로 사용한다. ZIP:ON 적용 판단은 MVP 문맥과 API 호출 순서 문맥을 함께 반영한다.
2. 원본 구조 요약
2.1 DOCX 구조
구분
원문 위치
내용
구현 관련성
표지
1쪽
공동주택 단지 식별정보 조회 서비스 Open API 활용가이드
낮음
목차
2쪽
서비스 명세, API 개요, 코드명세, 상세기능 목록, 상세기능내역, 에러 코드
보통
API 서비스 개요
3~4쪽
API명, 인증, REST GET, XML/JSON, 서비스 URL, 버전, 제공자, 갱신주기
이 API는 ZIP:ON의 핵심 위험도 계산 API라기보다, 공동주택 단지 식별과 물건 유형 보조에 쓰는 API다. ZIP:ON은 주소 입력 후 바로 실거래가를 조회하는 서비스가 아니라, 먼저 물건의 정체를 판별하고 그 결과에 따라 실거래가·공시가격·건축물대장 API를 선택해야 한다.
getAptInfo는 사용자가 입력한 주소가 아파트, 연립, 다세대 단지인지 확인하는 데 유용하다. 특히 COMPLEX_GB_CD, DONG_CNT, UNIT_CNT, USEAPR_DT, PNU는 위험도 계산 전 단계의 식별·분류·조합키로 쓸 수 있다.
다만 이 API만으로 다가구, 오피스텔, 근린생활시설 여부를 확정할 수 없고, 가격·권리관계·선순위 임차인·보증보험 가능성도 판단할 수 없다. 따라서 건축물대장, GIS건물통합정보, 실거래가, 공시가격 API와 조합해야 의미가 생긴다.
호출 순서는 주소 정제 → 법정동/PNU 후보 생성 → 건축물·GIS 기반 물건 유형 판별 → 공동주택 후보인 경우 AptIdInfoSvc 호출이 적합하다. 데이터 갱신주기가 매년이므로 결과는 DB 저장 또는 장기 캐시 후보지만, 실제 TTL은 운영 정책 확인이 필요하다.
조건 검색에서는 matchCount와 totalCount의 의미가 다를 수 있다. 예시상 getAptInfo는 currentCount=1, matchCount=1, totalCount=44064로 응답한다. 따라서 Codex 구현 시 기본 페이지 wrapper에는 두 값을 모두 보존하고, 반복 호출 기준은 실제 API 응답 검증 후 확정해야 한다.
필수 여부 변환 기준: 원문의 0은 선택이다. 다만 이 오퍼레이션은 complex_pk 또는 adres 중 하나 없이 호출했을 때 전체 목록이 반환되는지 확인 필요하다.
9.1.3 요청 예시
GET https://api.odcloud.kr/api/AptIdInfoSvc/v1/getAptInfo?page=1&perPage=10&cond%5BCOMPLEX_PK%3A%3AEQ%5D=11110100000033&cond%5BADRES%3A%3ALIKE%5D=%EC%84%9C%EC%9A%B8&serviceKey={SERVICE_KEY}
인코딩 전 의미:
GET https://api.odcloud.kr/api/AptIdInfoSvc/v1/getAptInfo?page=1&perPage=10&cond[COMPLEX_PK::EQ]=11110100000033&cond[ADRES::LIKE]=서울&serviceKey={SERVICE_KEY}
원문 요청표는 complex_pk, adres 소문자. 예시 URL과 응답 JSON은 COMPLEX_PK, ADRES 대문자. DTO 매핑 시 명시 필요
숫자형 문자열
COMPLEX_PK, PNU, 법정동코드류는 숫자처럼 보여도 문자열 처리
날짜 포맷
USEAPR_DT는 yyyyMMdd 문자열. XLSX 일부 날짜는 yyyy-MM-dd, yyyy/MM/dd, Excel serial처럼 보이는 값이 혼재하므로 원천별 파서 분리
응답 배열
data는 배열. 결과 0건일 때 빈 배열 가능성 처리
페이지 필드
matchCount와 totalCount 의미가 원문에 설명되지 않음. 실제 API 검증 필요
XML/JSON 차이
XML 지원 표기는 있으나 XML 예시는 없음. JSON 우선 구현 후 XML 필요성 확인
인증 실패
401은 사용자 입력 오류가 아니라 운영/인증 설정 문제로 처리
외부 API 장애
500, timeout, network error는 재시도/서킷브레이커 후보
전송 암호화 표기
원문 표는 SSL 없음, URL은 HTTPS. 실제 호출은 HTTPS 사용
no filter 호출
조건 없이 호출할 때 전체 목록 반환 여부, 비용, 제한 확인 필요
perPage 최대값
원문에 1회 요청 최대 건수 없음. 확인 필요
원천 데이터 갱신
데이터 갱신주기 매년. DB 저장 시 갱신 배치 정책 필요
공공데이터 포털 신청
활용신청/서비스키 발급 방식은 원문에 상세 없음. 확인 필요
XLSX 시트 간 참조
테이블정의서(전체/변동)의 비고 셀 일부가 참조코드의 코드그룹명을 참조하는 형태로 보임. 자동 파싱 시 원문 확인 필요
XLSX 다중 헤더
5~6행의 병합 헤더를 실제 컬럼명으로 복원해야 함
XLSX SHP/CSV 혼동
SHP 공간정보 컬럼과 CSV 속성정보 컬럼이 한 행에 병렬 배치되어 있음. 별도 스키마로 분리 필요
개인정보/마스킹
XLSX 부동산중개업/개발업 샘플에는 마스킹된 대표자/전화번호가 보임. 실제 데이터 저장 시 개인정보 여부 확인 필요
법적 판정 금지
이 API는 계약 안전성을 확정하지 않는다. ZIP:ON에서는 “추가 확인 필요” 문장으로 연결
14. API 조합 가능성
조합 대상 API
조합 목적
기대 결과
주의사항
주소 API
사용자 입력 주소 정제 후 본 API의 ADRES::LIKE 또는 다른 API 호출키 생성
정확한 단지 후보 검색
이 API 자체는 주소 정제 기능이 아님
법정동코드 API
주소에서 법정동코드, 시군구코드, 지번 분리
실거래가/건축물대장/토지 API 호출 기반
PNU에서 일부 정보를 추출할 수 있어도 전용 변환 API 필요
GIS건물통합정보
건물 존재, 용도, 위반건축물여부, 사용승인일, 층수 등과 결합
물건 정체 판별 정확도 향상
XLSX 컬럼정의서 기준으로 별도 API/파일 확보 필요
건축물대장 API
주용도, 대장구분, 전유부, 위반건축물 여부 확인
다가구/다세대/오피스텔 분기
AptIdInfoSvc는 공동주택 단지 식별 보조일 뿐 대장 원문 아님
실거래가 API
유형별 전월세/매매 거래가와 결합
전세가율, 월세 적정성, 매매가 비교
단지명 불일치 시 getHistInfo로 검색어 보정
공시가격 API
공동주택가격/개별주택가격과 결합
보증금 대비 기준가격 비교
COMPLEX_NM1, PNU, 법정동/지번 조합 필요
K-APT 공동주택 정보/관리비
단지 정보와 관리비 데이터 결합
관리비/단지 규모/공동주택 생활 분석
K-APT 단지코드와 complexPk 직접 매핑 여부 확인 필요
토지임야정보
PNU 기반 토지 속성 확인
지목, 면적, 대장구분 확인
공동주택 단지와 필지 관계가 1:1이 아닐 수 있음
용도지역지구도 API
용도지역·지구·구역과 결합
상가/토지/개발 가능성 보조
MVP 전월세에서는 우선순위 낮음
부동산중개업정보
중개사무소 등록/상태와 결합
계약 상대방·중개사 확인 체크리스트
전국 통합 형태와 최신성 확인 필요
15. Codex 작업 지시용 요약
# Codex 구현 목표이 문서를 바탕으로 `공동주택 단지 식별정보 조회 서비스(AptIdInfoSvc)` 외부 API 연동 코드를 구현한다.## 구현 대상- API Client- Request DTO- Response DTO- Service Layer- Error Mapping- Pagination 처리- JSON 응답 파싱- XML 응답 지원 여부 확인- 테스트 코드- 필요 시 DB 저장 또는 Redis 캐시## 구현 대상 오퍼레이션1. `getAptInfo` - Path: `/getAptInfo` - 주요 조건: `cond[COMPLEX_PK::EQ]`, `cond[ADRES::LIKE]` - 주요 응답: `COMPLEX_PK`, `PNU`, `ADRES`, `COMPLEX_NM1`, `COMPLEX_NM2`, `COMPLEX_NM3`, `COMPLEX_GB_CD`, `DONG_CNT`, `UNIT_CNT`, `USEAPR_DT`2. `getDongInfo` - Path: `/getDongInfo` - 주요 조건: `cond[COMPLEX_PK::EQ]` - 주요 응답: `COMPLEX_PK`, `DONG_NM1`, `DONG_NM2`, `DONG_NM3`, `GRND_FLR_CNT`3. `getHistInfo` - Path: `/getHistInfo` - 주요 조건: `cond[COMPLEX_PK::EQ]` - 주요 응답: `COMPLEX_PK`, `NM_CHAN_YEAR`, `COMPLEX_EX_NM`, `COMPLEX_PR_NM`## 공통 구현 방향- Base URL은 `https://api.odcloud.kr/api/AptIdInfoSvc/v1`로 둔다.- `serviceKey`는 환경변수 또는 Secret으로 주입한다.- 실제 인증키를 코드, 테스트, 문서에 하드코딩하지 않는다.- query parameter는 HTTP client의 query builder로 인코딩한다.- `cond[COMPLEX_PK::EQ]`와 `cond[ADRES::LIKE]`를 직접 문자열 결합하지 않는다.- 원문 요청표는 소문자 필드명을 쓰지만, 실제 URL 조건명과 응답 JSON은 대문자다.- 응답 DTO는 `@JsonProperty` 등으로 대문자 JSON 필드를 명시 매핑한다.- `COMPLEX_PK`, `PNU`, 법정동코드 계열 값은 숫자처럼 보여도 문자열로 처리한다.- `USEAPR_DT`는 `yyyyMMdd` 문자열로 받고 도메인 계층에서 날짜 변환한다.- 공통 응답 wrapper는 `currentCount`, `data`, `matchCount`, `page`, `perPage`, `totalCount`를 모두 보존한다.- 페이징 반복 기준은 실제 API 검증 전까지 `matchCount`와 `totalCount`를 모두 고려할 수 있게 구현한다.- 공공데이터 API 실패 응답을 도메인 예외로 변환한다.- 401은 인증키/설정 오류로 처리한다.- 500과 timeout은 외부 API 일시 장애로 처리한다.- 데이터 없음은 예외가 아니라 빈 결과로 처리한다.- ZIP:ON 도메인 서비스에서는 이 API 결과를 확정 판정이 아니라 물건 식별 보조 정보로 사용한다.- `COMPLEX_GB_CD`는 enum으로 매핑한다. - `1`: APARTMENT - `2`: ROW_HOUSE - `3`: MULTI_HOUSE- 이 API만으로 전세 위험도를 계산하지 않는다.- 건축물대장, GIS건물통합정보, 실거래가, 공시가격 API와 조합하는 서비스 계층을 별도로 둔다.- XLSX 원문에서 온 코드표/컬럼정의는 별도 reference 문서 또는 DB seed 후보로 분리한다.
16. 확인 필요 목록
항목
확인이 필요한 이유
250729의 의미
파일명에는 포함되어 있으나 본문 작성/개정일로 명시되어 있지 않음
서비스 명세 URL 접근 가능 여부
api-docs URL이 실제 OpenAPI/Swagger인지 확인 필요
개발환경 URL
원문에는 운영 URL만 있음
응답 포맷 선택 파라미터
XML/JSON 지원 표기는 있으나 _type, returnType 등 파라미터 없음
XML 응답 구조
XML 예시가 원문에 없음
page, perPage 최대값
원문에 1회 요청 최대 건수 없음
matchCount와 totalCount 의미
조건 검색 시 어떤 값을 페이지 반복 기준으로 삼을지 검증 필요
조건 없는 호출 동작
전체 목록 반환 여부, 비용, 제한 확인 필요
complex_pk 실사용 필수 여부
원문 항목구분은 선택이나 상세기능 설명상 단지고유번호 기반 조회
주소 LIKE 검색 정확도
ADRES::LIKE=서울처럼 넓은 검색 시 후보가 많을 수 있음
조건 연산자 종류
원문에는 EQ, LIKE만 예시로 나옴. 다른 연산자 지원 여부 확인 필요
HTTP status와 body error 구조
에러 코드 200/401/500만 있고 실패 응답 body 예시 없음
서비스키 인코딩 방식
공공데이터 서비스키는 인코딩키/디코딩키 이슈가 있을 수 있어 실제 호출 검증 필요
HTTPS/SSL 표기 불일치
원문 표에는 전송 레벨 암호화 없음, URL은 HTTPS
COMPLEX_GB_CD와 XLSX 공동주택구분코드 관계
AptIdInfoSvc 단지종류 코드와 XLSX 공동주택구분코드가 완전히 동일한 체계인지 확인 필요