Korea Ground-Truth / Tools / search_address

주소 정규화 API — 도로명주소·우편번호·법정동코드 변환

Korean Address Normalization API (road address, postal code, legal-dong code)

Cost: 1 credit/call (cache hit: 1). ≈ 10원/호출 · 출처: 행정안전부 (juso.go.kr) · 캐시 720시간

어떤 문제를 푸나

사용자가 입력한 지번·건물명·불완전한 주소를 공식 도로명주소, 우편번호(5자리), 행정구역코드, 영문주소로 바꿔야 합니다. 실거래가 조회에 필요한 법정동코드 5자리(lawd_code)도 함께 반환합니다.

• 배송지/청구지 정규화
• 영문 주소 생성 (해외 발송)
• 부동산·상권 분석 전 지역코드 확보
• 회원 DB 주소 클렌징

호출 방법

REST

curl -X POST https://kr-groundtruth-mcp.vercel.app/v1/tools/search_address \
  -H "Authorization: Bearer kgt_live_..." \
  -H "content-type: application/json" \
  -d '{"keyword":"테헤란로 152","per_page":2}'

MCP (Claude Code / Cursor / any MCP client)

claude mcp add --transport http kgt https://kr-groundtruth-mcp.vercel.app/api/mcp --header "Authorization: Bearer kgt_live_..."
# then ask: "search_address 툴로 {"keyword":"테헤란로 152","per_page":2} 조회해줘"

API 키 발급 (사람 불필요, 무료 50 credits)

curl -X POST https://kr-groundtruth-mcp.vercel.app/v1/accounts -H "content-type: application/json" -d '{"email":"you@example.com"}'

입력

응답 예시 (실제 응답, 2026-08-26)

{
  "ok": true,
  "data": {
    "source": "행정안전부 도로명주소 (juso.go.kr)",
    "total": 1,
    "page": 1,
    "results": [
      {
        "road_address": "서울특별시 강남구 테헤란로 152 (역삼동)",
        "road_address_main": "서울특별시 강남구 테헤란로 152",
        "road_address_detail": " (역삼동)",
        "jibun_address": "서울특별시 강남구 역삼동 737 강남파이낸스센터",
        "english_address": "152 Teheran-ro, Gangnam-gu, Seoul",
        "postal_code": "06236",
        "adm_code": "1168010100",
        "lawd_code": "11680",
        "building_name": "강남파이낸스센터",
        "sido": "서울특별시",
        "sigungu": "강남구",
        "eupmyeondong": "역삼동",
        "ri": null,
        "road_name": "테헤란로",
        "building_main_no": "152",
        "building_sub_no": "0",
        "is_underground": false,
        "is_mountain_lot": false,
        "lot_main_no": "737",
        "lot_sub_no": "0",
        "road_mgmt_no": "116803122010",
        "building_mgmt_no": "1168010100107370000023659"
      }
    ]
  },
  "meta": {
    "tool": "search_address",
    "cost": 1,
    "balance_remaining": 48,
    "cache_hit": false,
    "source": "행정안전부 (juso.go.kr)",
    "fetched_at": "2026-08-26T14:00:00.000Z",
    "usage_event_id": "usg_…"
  }
}

모든 응답은 meta.cost, meta.balance_remaining를 포함합니다. 업스트림 오류 시 자동 환불되며, 잔액 부족 시 402 INSUFFICIENT_CREDITS와 함께 충전 URL이 반환됩니다.

함께 쓰는 툴

• 아파트 실거래가 조회 API — 시군구·월별 매매 거래 내역 (국토교통부) — Cost: 3 credits/call (cache hit: 1).
• 사업자등록번호 조회 API — 계속사업자/휴업/폐업 상태 확인, 진위확인 — Cost: 2 credits/call (cache hit: 1).

llms.txt · openapi.json · pricing.json