zipcode-search

郵遞區號查詢

這個技能的功能

查詢郵局官方整合郵遞區號搜尋頁面，根據地址關鍵字找出對應的郵遞區號與官方英文地址。

使用時機

• 「幫我查這個地址的郵遞區號和英文地址」
• 「把首爾特別市江南區德黑蘭路123號轉成英文地址」
• 「海外付款需要韓國地址的英文寫法」

前置需求

• 網路連線
• curl
• python3

輸入

• 地址關鍵字
  • 道路名 + 建築編號
  • 市/郡/區 + 道路名
  • 洞/里 + 地號

工作流程

1. 先查詢 ePost 官方整合頁面

不要使用非官方的英文地址轉換器或部落格資料，直接查詢下方郵局官方整合搜尋頁面。

https://www.epost.kr/search.RetrieveIntegrationNewZipCdList.comm

這個頁面會透過 keyword 參數回傳郵遞區號、韓文地址，以及 English/집배코드 欄位的官方英文地址。

2. 用 curl 取得 HTML 並擷取 viewDetail(...) 行

目前 ePost 端點的回應可能偶爾會重設或超時，因此建議使用 curl --http1.1 --tls-max 1.2 加上重試機制，而不是直接用本機的 urllib。

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. 優先使用內建的 helper 以利重複執行

儲存庫中包含了包裝相同流程的可執行 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. 整理成易讀格式

回應是原始 HTML，不要直接貼上，請整理成以下格式：

• 郵遞區號
• 道路名韓文地址
• 官方英文地址
• 需要的話加上地號地址
• 如果有多個候選，只顯示前 3~5 個，並指出哪個最接近

5. 必要時用更精簡或更完整的關鍵字重試

如果搜尋不到結果，或一直超時/重設，請依序重試：

• 簡短道路名 + 建築編號：테헤란로 123
• 包含市/郡/區的完整地址：서울 강남구 테헤란로 123
• 洞/里 + 地號或替代寫法：역삼동 648-23

6. 在包裝的 shell 中優先使用暫存檔

在 CLI 包裝或代理 shell 中，here-doc 加 Python 單行可能會有問題，因此實務上建議先用 mktemp 之類的暫存檔儲存 HTML，再解析該檔案。如果只想看部分回應而加上 | head，可能會因為下游先關閉而出現 curl: (23) 錯誤，這種情況也應先將完整回應存到暫存檔再查看。

完成條件

• 至少整理出一個郵遞區號候選與官方英文地址
• 如果有多個候選，顯示韓文/英文地址的差異，讓使用者可以選擇
• 如果搜尋不到結果，建議重新搜尋的關鍵字方向

失敗模式

• 郵局搜尋頁面的標記改變時，viewDetail(...) 的擷取規則可能會失效
• 地址關鍵字太廣泛時，結果可能會過多
• 如果不重試，只呼叫一次可能會遇到暫時性的超時或重設錯誤
• 如果不用 curl 而直接使用其他客戶端，可能會發生協商或傳輸錯誤

備註

• 這是一個查詢型技能，保持官方標示不變
• 不涉及相對日期或即時概念，專注於地址字串的整理