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 而直接使用其他客户端可能导致协商/传输错误

备注

• 这是一个保持官方写法的查询型技能
• 不涉及相对日期/实时概念，专注于地址字符串的整理