주소
상태: 공통 표준 — 2026-10-10 KST 사용자 결정
적용 대상: company-wide — 사람·조직·사업자의 주소와 주소 종류(배송주소·청구주소·본점주소·사업장주소·자택주소)
정본 분류: 공통 규칙은 공통 입력 정보를 따릅니다. 이 쪽은 주소 필드의 정본입니다.
주소 필드
| 필드 | autocomplete | 코드 / DB | 한국어 라벨 | 영어 라벨 | 대응 표준 |
|---|---|---|---|---|---|
| 국가·지역 | country | country | 국가·지역 | Country or region | schema addressCountry, ISO 3166-1 alpha-2 |
| 우편번호 | postal-code | postalCode / postal_code | 우편번호 | Postal code | schema postalCode |
| 1단계 행정구역 | address-level1 | addressLevel1 / address_level1 | 한국: 시·도 | 나라별로 정함 | schema addressRegion |
| 2단계 행정구역 | address-level2 | addressLevel2 / address_level2 | 한국: 보통 시·군·구(세종특별자치시는 읍·면) | 나라별로 정함 | schema addressLocality |
| 3단계 행정구역 | address-level3 | addressLevel3 / address_level3 | 한국: 보통 읍·면 | 나라별로 정함 | — |
| 주소 | address-line1 | addressLine1 / address_line1 | 주소 | Address line 1 | schema streetAddress |
| 상세주소 | address-line2 | addressLine2 / address_line2 | 상세주소 | Address line 2 | schema extendedAddress |
| 나라 아래 행정구역 코드 | — | countrySubdivisionCode / country_subdivision_code | — | — | ISO 3166-2(KR-11) |
| 법정동 코드 | — | legalDistrictCode / legal_district_code | — | — | 도로명주소 API admCd |
country는 ISO 3166-1 두 글자 코드(KR)로 저장합니다. 나라 이름은 코드에서 화면 언어로 만듭니다.addressLevel3·addressLevel4·addressLine3은 그 단계가 필요한 나라·주소에서만 씁니다. 한국에서addressLevel3은 시·군·구 아래에 읍·면이 있는 주소에서만 씁니다(아래 「한국 주소의 저장」).- 행정 단계의 영어 라벨(State, City 등), 필수 여부, 표시 순서는 나라마다 다르므로 나라별로 정합니다.
- 여러 줄 입력(
street-address)과addressLine1–addressLine3중 하나만 정본으로 씁니다. 같은 주소를 두 모양으로 저장하지 않습니다. - 법정동 코드는 법정동 계열 코드입니다. 행정동 코드와 섞지 않습니다.
주소 종류
| 주소 종류 | addressType | 한국어 | 영어 | autocomplete 구역 | 대응 표준 |
|---|---|---|---|---|---|
| 배송주소 | shipping | 배송주소 | Shipping address | shipping | HTML |
| 청구주소 | billing | 청구주소 | Billing address | billing | HTML |
| 본점주소 | legal | 본점주소(민법 법인·법인 아닌 단체는 주사무소주소) | Registered address | section-legal | schema legalAddress |
| 사업장주소 | business | 사업장주소 | Business address | section-business | — |
| 자택주소 | home | 자택주소 | Home address | section-home | — |
- 「역할」이라고 부르지 않습니다. 「역할」은 접근 역할 체계의 접근 역할에만 씁니다.
- 라벨은 모두 「주소」로 끝냅니다(「배송지」·「소재지」 대신 「배송주소」·「사업장주소」). 법령 서식을 그대로 옮기는 화면과 출력물(사업자등록증의 「사업장 소재지」, 세금계산서의 칸 이름 등)만 서식의 용어를 씁니다.
shipping·billing은 실제 배송·청구 주소에만 씁니다. 다른 주소를 이 둘로 분류하지 않습니다.- 그 밖의 종류는 HTML 자동완성에서
section-*으로 묶음만 구분합니다(section-legal address-line1).section-*은 뜻이 없는 이름표입니다. - 저장: 정본은 주소 레코드와 「대상–주소–주소 종류」 관계 목록(
addresses)입니다. 같은 종류의 주소가 여럿일 수 있습니다. - API
- 레코드에 하나뿐인 종류(본점주소 등)는 단수 중첩 객체로 냅니다(
legalAddress: { country, postalCode, addressLine1, … }). - 여럿일 수 있는 종류(배송주소, 사업장주소 등)는 목록
addresses(각 항목에addressType)로 냅니다. 대표 하나를 가리키려면isPrimary를 둡니다.
- 레코드에 하나뿐인 종류(본점주소 등)는 단수 중첩 객체로 냅니다(
- 평면 접두어 필드(
businessAddressLine1,legalPostalCode)는 평면 입력·내보내기(CSV 등)에서만 씁니다.
한국 주소의 저장
주소는 주소 검색으로 확정합니다. 검색 결과 하나의 구조화 필드로 모든 칸을 함께 채우고, 주소를 바꿀 때도 함께 바꿉니다.
| 칸 | 넣는 값(도로명주소 API 기준) | HTML 정의 |
|---|---|---|
postalCode | 우편번호(zipNo) | postal-code |
addressLevel1 | 시·도 이름(siNm) | 1단계 행정구역 |
addressLevel2 · addressLevel3 | 시·도 아래의 행정 단계를 도로명주소에 나타나는 순서대로 빈칸 없이 채웁니다. 보통은 2단계가 시·군·구(sggNm, 「성남시 분당구」 같은 묶음 그대로), 3단계가 도로명주소에 든 읍·면(emdNm이 읍·면일 때)입니다. 세종특별자치시처럼 시·군·구가 없으면 읍·면이 2단계입니다. 동 지역은 읍·면 단계가 없습니다 | 2·3단계 행정구역 |
addressLine1 | 도로명과 건물번호(rn, 지하 여부 udrtYn, 건물 본번·부번 buldMnnm·buldSlno). 예: 「세종대로 110」 | 거리 주소 한 줄 |
addressLine2 | 동·호수 등 상세주소(사용자 입력) | 거리 주소 이어지는 줄 |
legalDistrictCode | 법정동 코드(admCd) | — |
countrySubdivisionCode | 시·도의 ISO 3166-2 코드(KR-11 등, 필요할 때) | — |
- 복원 규칙: 비어 있지 않은
addressLevel1·addressLevel2·addressLevel3·addressLine1을 공백으로 이으면 검색 결과의 도로명주소(roadAddrPart1)와 같아야 합니다. 저장할 때 이 규칙을 확인합니다. - 분해에 실패하면(복원 규칙이 맞지 않으면) 행정 단계 칸을 비우고 도로명주소 전체를
addressLine1에 넣습니다. 값은 겹치지 않지만, 이 상태의addressLine1은 HTMLaddress-line1정의와 다른 예외 상태입니다. 한국 주소에서addressLevel1(시·도)이 비어 있으면 이 상태이며, 다시 검색해 바로잡을 대상입니다. - 지역별 조회·통계는 늘 채워지는
legalDistrictCode를 먼저 씁니다. - 한 줄로 표시하거나 서식에 찍을 때는 복원한 도로명주소 다음에
addressLine2를 이어 씁니다. 필요하면 우편번호를 앞에 둡니다. - 본인 입력 화면에서 브라우저 자동완성이 채운 값도 주소 검색으로 다시 확정합니다.