Zipcode Search
What this skill does
우체국 공식 통합 우편번호 검색 페이지를 조회해서 주소 키워드에 맞는 우편번호와 공식 영문 주소를 함께 찾는다.
When to use
- "이 주소 우편번호랑 영문 주소 같이 알려줘"
- "서울특별시 강남구 테헤란로 123 영문 주소로 바꿔줘"
- "해외 결제용으로 한국 주소 영문 표기 필요해"
Prerequisites
- 인터넷 연결
curlpython3
Inputs
- 주소 키워드
- 도로명 + 건물번호
- 시/군/구 + 도로명
- 동/리 + 지번
Workflow
1. Query the official integrated ePost page first
비공식 영문주소 변환기나 블로그 표기를 쓰지 말고 아래 우체국 공식 통합 검색 페이지를 먼저 조회한다.
https://www.epost.kr/search.RetrieveIntegrationNewZipCdList.comm이 페이지는 keyword 파라미터로 우편번호, 국문 주소, English/집배코드 열의 공식 영문 주소를 함께 돌려준다.
2. Fetch the HTML with curl and extract the viewDetail(...) rows
현재 ePost 엔드포인트는 응답이 간헐적으로 reset/timeout 될 수 있으므로, 로컬 urllib 대신 curl --http1.1 --tls-max 1.2 + 재시도 경로를 기본 예시로 사용한다.
python3 - <<'PY'
import html
import re
import subprocess
query = "서울특별시 강남구 테헤란로 123"
cmd = [
"curl",
"--http1.1",
"--tls-max",
"1.2",
"--silent",
"--show-error",
"--location",
"--retry",
"3",
"--retry-all-errors",
"--retry-delay",
"1",
"--max-time",
"20",
"--get",
"--data-urlencode",
f"keyword={query}",
"https://www.epost.kr/search.RetrieveIntegrationNewZipCdList.comm",
]
page = subprocess.run(
cmd,
check=True,
capture_output=True,
text=True,
encoding="utf-8",
).stdout
matches = re.findall(
r"viewDetail\('([^']*)','([^']*)','([^']*)','([^']*)',\s*'[^']*'\)",
page,
)
if not matches:
raise SystemExit("검색 결과가 없습니다.")
for zip_code, road_address, english_address, jibun_address in matches[:5]:
print(zip_code)
print(html.unescape(road_address))
print(html.unescape(english_address))
print(html.unescape(jibun_address))
print("---")
PY핵심 값은 viewDetail(zip, roadAddress, englishAddress, jibunAddress, rowIndex) 인자다. 공식 출력은 보통 123, Teheran-ro, Gangnam-gu, Seoul, 06133, Rep. of KOREA 같은 형식을 그대로 준다.
3. Prefer the shipped helper for repeatable execution
저장소에는 같은 흐름을 감싼 실행 가능한 helper가 포함되어 있다.
python3 scripts/zipcode_search.py "서울특별시 강남구 테헤란로 123"
./scripts/zipcode_search.py "서울특별시 강남구 테헤란로 123"예시 출력:
{
"query": "서울특별시 강남구 테헤란로 123",
"results": [
{
"zip_code": "06133",
"road_address": "서울특별시 강남구 테헤란로 123 (역삼동, 여삼빌딩)",
"english_address": "123, Teheran-ro, Gangnam-gu, Seoul, 06133, Rep. of KOREA",
"jibun_address": "서울특별시 강남구 역삼동 648-23 (여삼빌딩)"
}
]
}4. Normalize for humans
응답은 raw HTML이므로 그대로 붙이지 말고 아래처럼 정리한다.
- 우편번호
- 도로명 국문 주소
- 공식 영문 주소
- 필요하면 지번 주소
- 후보가 여러 개면 상위 3~5개만 보여주고 어느 항목이 가장 근접한지 짚기
5. Retry with tighter and fuller keywords when needed
검색 결과가 없거나 timeout/reset이 반복되면 아래 순서로 재시도한다.
- 짧은 도로명 + 건물번호:
테헤란로 123 - 시/군/구 포함 전체 주소:
서울 강남구 테헤란로 123 - 동/리 + 지번 또는 대체 표기:
역삼동 648-23
6. Prefer temp files in wrapped shells
CLI 래퍼나 에이전트 쉘에서는 here-doc + Python one-liner가 깨질 수 있으므로, 실전에서는 mktemp 같은 임시 파일에 HTML을 저장한 뒤 그 파일을 파싱하는 경로를 우선한다. 응답 일부만 보려고 | head 를 붙이면 다운스트림이 먼저 닫히면서 curl: (23) 이 보일 수 있으니, 이 경우도 전체 응답을 임시 파일에 저장한 뒤 확인한다.
Done when
- 적어도 한 개의 우편번호 후보와 공식 영문 주소가 정리되어 있다
- 다중 후보일 때 사용자가 고를 수 있게 국문/영문 주소 차이가 보인다
- 검색 결과가 없으면 재검색 키워드 방향을 제안했다
Failure modes
- 우체국 검색 페이지 마크업이 바뀌면
viewDetail(...)추출 규칙이 깨질 수 있다 - 주소 키워드가 너무 넓으면 결과가 과하게 많아질 수 있다
- 재시도 없이 한 번만 호출하면 timeout/reset 같은 일시 오류가 날 수 있다
curl없이 다른 클라이언트로 바로 붙으면 협상/전송 오류가 날 수 있다
Notes
- 공식 표기 그대로 유지하는 조회형 스킬이다
- 상대 날짜/실시간 개념은 없으므로 주소 문자열 정제에 집중한다
