juso

키워드로 한국 우편번호와 주소를 검색하는 CLI 도구이자 Go 라이브러리입니다.

설치

Homebrew

brew install kyungw00k/cli/juso

Go

go install github.com/kyungw00k/juso/cmd/juso@latest

Shell Script

curl -fsSL https://kyungw00k.dev/juso/install.sh | sh

사용법

juso 테헤란로                      # 우편번호 검색
juso 판교역로 --lang en            # 영문 주소 출력
juso 강남대로 --lang all           # 한/영 동시 출력
juso 역삼동 --jibun                # 지번 주소 출력
juso 테헤란로 -o json              # JSON 출력
juso 테헤란로 -o csv > results.csv # CSV 내보내기

출력 예시

$ juso 테헤란로
우편번호  주소
06134     서울특별시 강남구 테헤란로 101
06134     서울특별시 강남구 테헤란로 103
06232     서울특별시 강남구 테헤란로 108
06142     서울특별시 강남구 테헤란로 110

$ juso 테헤란로 --lang en
우편번호  주소
06134     101, Teheran-ro, Gangnam-gu, Seoul
06134     103, Teheran-ro, Gangnam-gu, Seoul
06232     108, Teheran-ro, Gangnam-gu, Seoul

CLI 옵션

플래그	기본값	설명
`-o, --output`	`auto`	출력 형식: `auto`, `table`, `json`, `jsonl`, `csv`
`--lang`	`ko`	주소 언어: `ko`, `en`, `all` (ASCII 키워드는 자동으로 `en`)
`--jibun`	`false`	지번 주소 출력 (기본: 도로명)

출력 형식

형식	설명
`auto`	터미널이면 `table`, 파이프면 `json`
`table`	사람이 읽기 좋은 테이블
`json`	JSON (터미널: pretty, 파이프: compact)
`jsonl`	JSON Lines (스트리밍용)
`csv`	CSV (전체 필드 포함)

서브커맨드

juso cache stats        # 캐시 통계 (건수, 크기)
juso cache clear        # 캐시 전체 삭제
juso tool-schema        # AI Agent용 JSON Schema 출력
juso tool-schema search # 검색 명령어 Schema만
juso update             # 최신 버전으로 업데이트
juso update --check     # 업데이트 확인만

캐시

검색 결과는 SQLite에 로컬 캐시됩니다 (TTL: 24시간).

캐시 경로 우선순위:

$XDG_CACHE_HOME/juso/cache.db
~/.cache/juso/cache.db (~/.cache 존재 시)
~/.juso/cache.db

라이브러리로 사용

import "github.com/kyungw00k/juso"

results, err := juso.Search(ctx, "강남역")
for _, r := range results {
    fmt.Println(r.Postcode5, r.KoAddress)
    fmt.Println(r.EnAddress)
    fmt.Println(r.KakaoMapURL)
}

옵션 지정

results, err := juso.SearchWithOptions(ctx, "강남역", &juso.Options{
    Timeout: 5 * time.Second,
})

응답 필드

필드	설명
`Postcode5`	5자리 우편번호
`Postcode6`	6자리 우편번호 (구)
`KoAddress`	한국어 도로명 주소
`KoJibun`	한국어 지번 주소
`EnAddress`	영문 도로명 주소
`EnJibun`	영문 지번 주소
`BuildingName`	건물명
`KakaoMapURL`	카카오맵 검색 링크
`NaverMapURL`	네이버지도 검색 링크

AI Agent 연동

tool-schema 명령으로 JSON Schema를 내보내 LLM/MCP 도구로 사용할 수 있습니다.

juso tool-schema

Claude Code Skill

AI 에이전트가 juso를 자동으로 활용할 수 있는 Claude Code 스킬이 제공됩니다.

/plugin marketplace add kyungw00k/skills
/plugin install cli-tools@kyungw00k-skills

문서

https://kyungw00k.dev/juso/

Credits

주소 데이터는 Postcodify API를 통해 제공됩니다. Postcodify는 poesis가 개발한 한국 우편번호 검색 엔진입니다.

License

MIT

juso는 Postcodify의 HTTP API를 호출하며, Postcodify 소스코드를 포함하거나 배포하지 않습니다.

Name		Name	Last commit message	Last commit date
Latest commit History 24 Commits
.claude		.claude
.github/workflows		.github/workflows
api		api
cache		cache
cmd/juso		cmd/juso
docs		docs
internal		internal
.gitignore		.gitignore
.goreleaser.yml		.goreleaser.yml
CLAUDE.md		CLAUDE.md
Makefile		Makefile
README.md		README.md
go.mod		go.mod
go.sum		go.sum
juso.go		juso.go
juso_test.go		juso_test.go
plugin.json		plugin.json
types.go		types.go
types_test.go		types_test.go

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

juso

설치

Homebrew

Go

Shell Script

사용법

출력 예시

CLI 옵션

출력 형식

서브커맨드

캐시

라이브러리로 사용

옵션 지정

응답 필드

AI Agent 연동

Claude Code Skill

문서

Credits

License

About

Uh oh!

Releases 3

Sponsor this project

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

juso

설치

Homebrew

Go

Shell Script

사용법

출력 예시

CLI 옵션

출력 형식

서브커맨드

캐시

라이브러리로 사용

옵션 지정

응답 필드

AI Agent 연동

Claude Code Skill

문서

Credits

License

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases 3

Sponsor this project

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages