郵便番号検索

このスキルが行うこと

Korea Post（郵便局）公式統合郵便番号検索ページを照会して、アドレスキーワードに合致する郵便番号と公式英文アドレスを一緒に検索します。

使用場面

• 「このアドレスの郵便番号と英文アドレスを教えてください」
• 「ソウル特別市江南区テヘラン路 123 の英文アドレスに変換してください」
• 「海外決済用に韓国アドレスの英文表記が必要です」

前提条件

• インターネット接続
• curl
• python3

入力

• アドレスキーワード
  • 道路名 + 建物番号
  • 市/郡/区 + 道路名
  • 洞/里 + 地番

ワークフロー

1. 公式統合 ePost ページを最初に照会する

非公式の英文アドレス変換ツールやブログ表記を使用せず、以下の Korea Post 公式統合検索ページを最初に照会します。

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

このページは keyword パラメータで郵便番号、国文アドレス、English/集配コード 列の公式英文アドレスを一緒に返します。

2. curl で HTML を取得し、viewDetail(...) 行を抽出する

現在の ePost エンドポイントはレスポンスが断続的にリセット/タイムアウトする可能性があるため、ローカル 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. 繰り返し実行用に付属のヘルパーを優先する

リポジトリには同じフローをラップした実行可能なヘルパーが含まれています。

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. ユーザー向けに正規化する

レスポンスは raw HTML なので、そのままではなく以下のように整理します。

• 郵便番号
• 道路名国文アドレス
• 公式英文アドレス
• 必要に応じて地番アドレス
• 候補が複数ある場合は上位 3～5 件のみを表示し、どの項目が最も近いか指摘する

5. 必要に応じてより厳密で完全なキーワードで再試行する

検索結果がないか、タイムアウト/リセットが繰り返される場合は、以下の順序で再試行します。

• 短い道路名 + 建物番号：테헤란로 123
• 市/郡/区を含む全アドレス：서울 강남구 테헤란로 123
• 洞/里 + 地番または代替表記：역삼동 648-23

6. ラップされたシェルで一時ファイルを優先する

CLI ラッパーまたはエージェントシェルでは、here-doc + Python ワンライナーが破損する可能性があるため、実運用では mktemp などの一時ファイルに HTML を保存し、そのファイルをパースするパスを優先します。レスポンスの一部のみを見ようと | head を付けると、ダウンストリームが先に閉じるため curl: (23) が表示される可能性がありますので、この場合も全レスポンスを一時ファイルに保存してから確認します。

完了条件

• 少なくとも 1 つの郵便番号候補と公式英文アドレスが整理されている
• 複数候補の場合、ユーザーが選択できるよう国文/英文アドレスの違いが見える
• 検索結果がない場合、再検索キーワード方向を提案している

失敗モード

• Korea Post 検索ページのマークアップが変わると、viewDetail(...) 抽出ルールが破損する可能性がある
• アドレスキーワードが広すぎると、結果が過度に多くなる可能性がある
• 再試行なしで 1 回だけ呼び出すと、タイムアウト/リセットなどの一時的なエラーが発生する可能性がある
• curl なしで他のクライアントで直接接続すると、ネゴシエーション/送信エラーが発生する可能性がある

注記

• 公式表記をそのまま保持する照会型スキルです
• 相対日付/リアルタイムの概念はないため、アドレス文字列のクリーニングに焦点を当てます