zipcode-search

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Zipcode Search

邮政编码查询

What this skill does

技能功能

우체국 공식 통합 우편번호 검색 페이지를 조회해서 주소 키워드에 맞는 우편번호와 공식 영문 주소를 함께 찾는다.

通过查询韩国邮政官方综合邮政编码搜索页面，查找与地址关键词匹配的邮政编码及官方英文地址。

When to use

使用场景

"이 주소 우편번호랑 영문 주소 같이 알려줘"
"서울특별시 강남구 테헤란로 123 영문 주소로 바꿔줘"
"해외 결제용으로 한국 주소 영문 표기 필요해"

"帮我查这个地址的邮政编码和英文地址"
"帮我把首尔特别市江南区德黑兰路123号转换成英文地址"
"需要韩国地址的英文表述用于海外支付"

Prerequisites

前置条件

인터넷 연결
```
curl
```
```
python3
```

网络连接
```
curl
```
```
python3
```

Inputs

输入参数

주소 키워드
- 도로명 + 건물번호
- 시/군/구 + 도로명
- 동/리 + 지번

地址关键词
- 道路名 + 建筑编号
- 市/郡/区 + 道路名
- 洞/里 + 地籍号

Workflow

工作流程

1. Query the official integrated ePost page first

1. 首先查询官方ePost综合页面

비공식 영문주소 변환기나 블로그 표기를 쓰지 말고 아래 우체국 공식 통합 검색 페이지를 먼저 조회한다.

text

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

이 페이지는

keyword

파라미터로 우편번호, 국문 주소,

English/집배코드

열의 공식 영문 주소를 함께 돌려준다.

请勿使用非官方英文地址转换器或博客表述，优先查询以下韩国邮政官方综合搜索页面。

text

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

该页面通过

keyword

参数返回邮政编码、韩文地址、

English/집배코드

列的官方英文地址。

2. Fetch the HTML with curl and extract the

viewDetail(...)

rows

2. 使用curl获取HTML并提取

viewDetail(...)

行

현재 ePost 엔드포인트는 응답이 간헐적으로 reset/timeout 될 수 있으므로, 로컬

urllib

대신

curl --http1.1 --tls-max 1.2

+ 재시도 경로를 기본 예시로 사용한다.

bash

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

같은 형식을 그대로 준다.

由于当前ePost端点可能会间歇性出现重置/超时情况，因此默认示例使用

curl --http1.1 --tls-max 1.2

+重试机制，而非本地

urllib

。

bash

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

3. 优先使用内置工具进行重复执行

저장소에는 같은 흐름을 감싼 실행 가능한 helper가 포함되어 있다.

bash

python3 scripts/zipcode_search.py "서울특별시 강남구 테헤란로 123"
./scripts/zipcode_search.py "서울특별시 강남구 테헤란로 123"

예시 출력:

json

{
  "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 (여삼빌딩)"
    }
  ]
}

仓库中包含了封装相同流程的可执行工具。

bash

python3 scripts/zipcode_search.py "서울특별시 강남구 테헤란로 123"
./scripts/zipcode_search.py "서울특별시 강남구 테헤란로 123"

示例输出:

json

{
  "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

4. 整理为便于阅读的格式

응답은 raw HTML이므로 그대로 붙이지 말고 아래처럼 정리한다.

우편번호
도로명 국문 주소
공식 영문 주소
필요하면 지번 주소
후보가 여러 개면 상위 3~5개만 보여주고 어느 항목이 가장 근접한지 짚기

由于返回的是原始HTML，请勿直接粘贴，需按以下方式整理：

邮政编码
韩文道路名地址
官方英文地址
必要时提供地籍号地址
若有多个候选结果，仅展示前3~5个，并指出最匹配的条目

5. Retry with tighter and fuller keywords when needed

5. 必要时使用更精准或完整的关键词重试

검색 결과가 없거나 timeout/reset이 반복되면 아래 순서로 재시도한다.

짧은 도로명 + 건물번호:
```
테헤란로 123
```
시/군/구 포함 전체 주소:
```
서울 강남구 테헤란로 123
```
동/리 + 지번 또는 대체 표기:
```
역삼동 648-23
```

若未找到搜索结果或反复出现超时/重置情况，请按以下顺序重试：

简短道路名+建筑编号：
```
테헤란로 123
```
包含市/郡/区的完整地址：
```
서울 강남구 테헤란로 123
```
洞/里+地籍号或替代表述：
```
역삼동 648-23
```

6. Prefer temp files in wrapped shells

6. 在封装shell中优先使用临时文件

CLI 래퍼나 에이전트 쉘에서는 here-doc + Python one-liner가 깨질 수 있으므로, 실전에서는

mktemp

같은 임시 파일에 HTML을 저장한 뒤 그 파일을 파싱하는 경로를 우선한다. 응답 일부만 보려고

| head

를 붙이면 다운스트림이 먼저 닫히면서

curl: (23)

이 보일 수 있으니, 이 경우도 전체 응답을 임시 파일에 저장한 뒤 확인한다.

在CLI包装器或Agent shell中，here-doc + Python单行代码可能会失效，因此实际使用时优先采用将HTML保存至

mktemp

等临时文件后再解析的方式。若为查看部分响应而添加

| head

，可能会因下游提前关闭而出现

curl: (23)

错误，这种情况下也需将完整响应保存至临时文件后再查看。

Done when

完成条件

적어도 한 개의 우편번호 후보와 공식 영문 주소가 정리되어 있다
다중 후보일 때 사용자가 고를 수 있게 국문/영문 주소 차이가 보인다
검색 결과가 없으면 재검색 키워드 방향을 제안했다

已整理出至少一个邮政编码候选及官方英文地址
若有多个候选结果，需展示韩文/英文地址的差异以便用户选择
若未找到搜索结果，需提供重新搜索的关键词方向

Failure modes

失败场景

우체국 검색 페이지 마크업이 바뀌면
```
viewDetail(...)
```
추출 규칙이 깨질 수 있다
주소 키워드가 너무 넓으면 결과가 과하게 많아질 수 있다
재시도 없이 한 번만 호출하면 timeout/reset 같은 일시 오류가 날 수 있다
```
curl
```
없이 다른 클라이언트로 바로 붙으면 협상/전송 오류가 날 수 있다

若韩国邮政搜索页面的标记语言发生变化，
```
viewDetail(...)
```
提取规则可能失效
地址关键词过于宽泛可能导致结果过多
若不进行重试仅调用一次，可能出现超时/重置等临时错误
若不使用
```
curl
```
而直接使用其他客户端，可能出现协商/传输错误

Notes

注意事项

공식 표기 그대로 유지하는 조회형 스킬이다
상대 날짜/실시간 개념은 없으므로 주소 문자열 정제에 집중한다

这是一款严格保留官方表述的查询类技能
无相对日期/实时概念，需专注于地址字符串的整理

zipcode-search

Original

Translation

Zipcode Search

邮政编码查询

What this skill does

技能功能

When to use

使用场景

Prerequisites

前置条件

Inputs

输入参数

Workflow

工作流程

1. Query the official integrated ePost page first

1. 首先查询官方ePost综合页面

2. Fetch the HTML with curl and extract the
`viewDetail(...)`
rows

2. 使用curl获取HTML并提取
`viewDetail(...)`
行

3. Prefer the shipped helper for repeatable execution

3. 优先使用内置工具进行重复执行

4. Normalize for humans

4. 整理为便于阅读的格式

5. Retry with tighter and fuller keywords when needed

5. 必要时使用更精准或完整的关键词重试

6. Prefer temp files in wrapped shells

6. 在封装shell中优先使用临时文件

Done when

完成条件

Failure modes

失败场景

Notes

注意事项

zipcode-search

Original

Translation

Zipcode Search

邮政编码查询

What this skill does

技能功能

When to use

使用场景

Prerequisites

前置条件

Inputs

输入参数

Workflow

工作流程

1. Query the official integrated ePost page first

1. 首先查询官方ePost综合页面

2. Fetch the HTML with curl and extract the viewDetail(...) rows

2. 使用curl获取HTML并提取viewDetail(...)行

3. Prefer the shipped helper for repeatable execution

3. 优先使用内置工具进行重复执行

4. Normalize for humans

4. 整理为便于阅读的格式

5. Retry with tighter and fuller keywords when needed

5. 必要时使用更精准或完整的关键词重试

6. Prefer temp files in wrapped shells

6. 在封装shell中优先使用临时文件

Done when

完成条件

Failure modes

失败场景

Notes

注意事项

2. Fetch the HTML with curl and extract the
`viewDetail(...)`
rows

2. 使用curl获取HTML并提取
`viewDetail(...)`
行