juso-address-cli

Minimal command-line wrapper for the 행정안전부 주소기반산업지원서비스 (juso.go.kr) OpenAPI.

Three operations:

1. search — keyword search for 도로명주소 / 지번주소 with 우편번호 (KR).
2. eng — English road-address search (for non-Korean-speaking users).
3. coord — address → WGS84-ish 좌표 (entrance-coordinate API, grade-B key required).

All output is compact JSON, one object per line (JSONL) for easy piping into jq or agent post-processing.

When to use this skill

Use when the task is Korean-address-shaped:

• "Find the full 도로명주소 and 우편번호 for 강남대로 123"
• "Normalize this user-entered address against the government registry"
• "Give me the 영문주소 for 서울특별시 종로구 세종대로 209"
• "Get the entrance lat/lng of this address so I can drop a pin"

Do not use this skill to:

• Do a free-form place search (use kakao-local-cli keyword search instead).
• Reverse-geocode coordinates (juso.go.kr does not publish a reverse endpoint — use kakao-local-cli coord2addr).

Prerequisites

1. Request a 확인키 (confmKey) at \x3Chttps://business.juso.go.kr/addrlink/openApi/apiExprn.do>. Grade-A (개발용) is granted instantly; grade-B (운영용) is granted within 1–2 business days and is required for coord.
2. Export the key:

   export JUSO_CONFM_KEY="devU01TX0FVVEgyMDI1..."     # for search/eng
   export JUSO_CONFM_KEY_COORD="U01TX0FVVEgyMDI1..."  # grade-B, for coord
   

3. Dependencies: bash, curl, jq, python3 (all default on macOS/Linux).

Commands

# 1) Keyword search (도로명 or 지번)
scripts/search.sh "강남대로 123"
scripts/search.sh "세종대로 209" --per-page 20 --page 1 --history Y

# 2) English address search
scripts/eng.sh "Sejongdae-ro 209"

# 3) Address → entrance coordinates (grade-B key required)
scripts/coord.sh --admcode 1111000000 \
  --rnmgmcd 111104166021 --udrtyn 0 \
  --buldmnnm 209 --buldslno 0

# Helper: resolve a raw address string to coordinates in one call.
# Internally: search → pick first result → coord.
scripts/resolve.sh "서울특별시 종로구 세종대로 209"

Every script prints one JSON object per line on stdout; errors go to stderr with a non-zero exit code.

Example JSONL output

{"roadAddr":"서울특별시 종로구 세종대로 209","jibunAddr":"서울특별시 종로구 세종로 55-1 정부서울청사","zipNo":"03171","bdNm":"정부서울청사","siNm":"서울특별시","sggNm":"종로구","emdNm":"세종로","rn":"세종대로","buldMnnm":"209","buldSlno":"0","admCd":"1111051500","rnMgtSn":"111104166021","bdMgtSn":"1111010100100550001000001","udrtYn":"0"}

Rate limits

• juso.go.kr caps free keys at 10 requests/sec and 30,000 requests/day per key (grade-A) / 100,000/day (grade-B). The scripts do not retry on 429 — back off in the caller.

Notes for agents

• Always pipe search.sh through jq -s '.[0]' (or head -n1) when you only need the best match.
• resolve.sh is the one-shot convenience: it silently picks the first search hit and then hits coord, so it requires both keys. Fail back to search.sh alone when JUSO_CONFM_KEY_COORD is absent.
• The 우편번호 (zipNo) returned here is the 5-digit 기초구역번호 (post-2015), not the legacy 6-digit code.
• Input may mix 도로명 and 지번; juso.go.kr accepts both and returns a normalized roadAddr.
• English search requires the street stem in Revised Romanization (e.g. "Sejongdae-ro", not "Sejong-daero").

Reference

• Official API docs: \x3Chttps://business.juso.go.kr/addrlink/openApi/apiExprn.do>
• Error-code list: \x3Chttps://business.juso.go.kr/addrlink/devCenterEventBoard/devBoardList.do?cPath=99MD>
• License: MIT (this CLI wrapper). The underlying data is public under 공공데이터 이용 약관.