해외 주소 처리 경험이 있어도 한국 주소에서는 다시 걸립니다. 구조가 다르고, 표기 규칙에 예외가 많고, 무엇보다 상세주소가 자유 입력이라는 점이 설계를 흔듭니다. 아래는 실제로 데이터 사고나 배송 실패로 이어지는 지점들입니다. 알고 나면 당연하지만, 모르면 반드시 한 번은 밟습니다.
우편번호를 숫자로 다루면 앞자리 0이 사라진다
가장 흔하고 가장 조용히 터지는 문제입니다. 서울 지역 우편번호는 0으로 시작합니다. 이걸 정수형으로 저장하거나 CSV로 내보내면 06236이 6236이 됩니다.
문제는 에러가 나지 않는다는 점입니다. 값은 멀쩡히 저장되고, 배송 라벨이 출력될 때까지 아무도 모릅니다. 우편번호는 숫자가 아니라 다섯 자리 문자열로 다뤄야 합니다. 자리수 검증도 함께 넣으세요. 우편번호 체계의 배경은 우편번호 5자리의 의미에 정리돼 있습니다.
옛 6자리 우편번호가 아직 남아 있다
2015년에 5자리로 바뀌었지만, 오래된 데이터베이스에는 135-080 형태가 그대로 있습니다. 하이픈이 들어간 여섯 자리를 만나면 폐지된 번호이므로 주소로 다시 조회해 5자리를 받아야 합니다. 하이픈만 제거해 다섯 자리로 자르는 처리는 완전히 다른 지역을 가리키게 만듭니다.
상세주소는 정규화할 수 없다
도로명주소 체계는 건물번호까지만 공식 표기를 제공합니다. 그 뒤 동·호수는 사용자가 자유롭게 씁니다. 같은 세대가 이렇게 들어옵니다.
완벽한 파서를 만들려 하면 예외가 끝없이 나옵니다. 현실적인 목표는 동 숫자와 호 숫자만 추출하는 것입니다. 두 값만 확보하면 Apt 101-1502로 통일할 수 있습니다. 추출에 실패하면 원본을 그대로 두고 사람이 보게 넘기세요.
도로명의 하이픈은 의미가 있다
테헤란로8길은 Teheran-ro 8-gil입니다. 하이픈을 공백으로 바꾸거나 지우면 다른 도로가 됩니다. 특히 「번길」은 beon-gil로, 「길」은 gil로 구분됩니다.
| 한글 | 올바른 표기 | 흔한 오류 |
|---|---|---|
| 테헤란로 | Teheran-ro | Teheran Road |
| 테헤란로8길 | Teheran-ro 8-gil | Teheran-ro 8 Street |
| 테헤란로8번길 | Teheran-ro 8beon-gil | Teheran-ro 8-gil |
| 강남대로 | Gangnam-daero | Gangnam Avenue |
접미사별 규칙은 도로명 접미사 영문 표기에서 자세히 다룹니다.
지명을 번역하면 안 된다
「로」를 Road로, 「구」를 District로 옮기는 처리는 직관적이지만 틀립니다. 한국의 영문주소 표기는 번역이 아니라 로마자 전사입니다. Gangnam-gu이지 Gangnam District가 아닙니다.
번역된 주소도 국내 배송에서는 대체로 도착합니다. 그래서 문제가 늦게 발견됩니다. 하지만 해외 서식 검증이나 관공서 서류에서는 반려됩니다. 자동 번역 라이브러리를 주소에 적용하지 마세요.
시·도와 시·군·구를 뒤집어 매핑한다
해외 양식의 State와 City에 무엇을 넣을지에서 자주 뒤집힙니다.
City → 강남구, 수원시 (기초 단위)
「구」를 City에 넣는 게 어색해 보여 State에 넣는 구현이 종종 보이는데, 그러면 국제 구간 분류가 꼬입니다. 광역 단위 17개의 정식 영문 표기는 행정구역 영문 표기표에 있습니다.
주소 필드에 주소가 아닌 값이 들어온다
자유 입력 필드에는 무엇이든 들어옵니다. 「위와 같음」, 「직접 수령」, 전화번호, 이메일, 빈 문자열. 이런 값을 변환 로직에 그대로 넣으면 실패율 지표가 오염되고, 진짜 문제를 가립니다.
1차 필터로 광역 단위 명칭 포함 여부를 검사하면 대부분 걸러집니다. 걸러진 값은 실패가 아니라 변환 대상 아님으로 따로 분류하세요. 이 구분이 있어야 실패율이 의미 있는 지표가 됩니다.
설계에 반영할 것
- 우편번호는 5자리 문자열, 자리수 검증 필수
- 6자리 발견 시 주소로 재조회
- 도로명과 상세주소는 별도 필드
- 상세주소는 동·호 숫자만 추출, 실패하면 원본 보존
- 번역이 아니라 전사 — 자동 번역 금지
- 광역=State, 기초=City
- 변환 실패와 변환 대상 아님을 구분
정리된 데이터를 한 번에 바꾸려면 대량 변환기를, 시스템에 붙이려면 변환 API를 쓰면 됩니다. 결과 점검은 표기 검사기로 표본만 돌려도 대부분의 오류 유형이 드러납니다.
자주 묻는 질문
우편번호를 정수형으로 저장하면 안 되나요?
안 됩니다. 서울 지역은 0으로 시작하므로 정수형에 담으면 앞자리가 사라지고, 에러 없이 조용히 값이 망가집니다. 다섯 자리 문자열로 저장하고 자리수를 검증하세요.
상세주소 파서를 만들 가치가 있나요?
동 숫자와 호 숫자만 뽑는 수준이면 가치가 있습니다. 그 이상을 노리면 예외 처리에 드는 비용이 얻는 것보다 큽니다. 추출에 실패한 건은 원본을 보존해 사람이 확인하도록 넘기세요.
「로」를 Road로 번역해도 배송은 되던데요?
국내 배송에서는 대체로 도착합니다. 문제는 해외 양식 검증이나 관공서 서류에서 반려된다는 점입니다. 공식 표기는 번역이 아니라 로마자 전사이므로 Teheran-ro가 맞습니다.
State 칸에 구(gu)를 넣으면 어떻게 되나요?
국제 구간에서 지역 분류가 어긋납니다. State에는 서울·경기도 같은 광역 단위를, City에는 강남구·수원시 같은 기초 단위를 넣어야 합니다.
변환 실패율은 어느 정도가 정상인가요?
데이터 출처에 따라 다르므로 절대 수치보다 변화를 보세요. 평소 수준을 기록해 두고 갑자기 뛰면 연동이나 데이터 유입 쪽 문제를 의심하는 방식이 실용적입니다.