`GET` /addresses

The verified English form of a Korean road address — the government's own value, not a transliteration. Send it in Korean or already romanised. Free, but a key is required. Why the official value, and how complete it is.

curl -H "Authorization: Bearer $KCID_KEY" \
  ".../addresses?q=11 Gukhoe-daero 72-gil, Yeongdeungpo-gu, Seoul"

{
  "query": "11 Gukhoe-daero 72-gil, Yeongdeungpo-gu, Seoul",
  "address_en": "11 Gukhoe-daero 72-gil, Yeongdeungpo-gu, Seoul",
  "address_ko": "서울특별시 영등포구 국회대로72길 11",
  "postal_code": "07238",
  "source": "mois_official",
  "credits_charged": 0
}

Korean input works the same way — ?q=서울 영등포구 국회대로72길 11 returns exactly this. English input must be the official romanisation, though: 삼성로 is registered as Samsung-ro, not Samseong-ro, so a guessed spelling finds nothing. Why guessing does not work.

Send a full address. A road name without a building number matches every building on that road — Samseong-ro matches 5,271 — so you get 409 with the count and up to ten candidates rather than an arbitrary pick.

{
  "error": { "code": "ambiguous", "message": "5,271 addresses match…" },
  "total_matches": 5271,
  "candidates": [ { "address_en": "…", "address_ko": "…", "postal_code": "…" } ],
  "candidates_note": "The first 10 of 5,271 in register order. They are not ranked…"
}

An address the register cannot resolve returns 404 not_found rather than a guess — this endpoint never falls back to a rule. Stored company records do, and say so in address_en_method.

Missing an endpoint or a field? Say what you were trying to do — it is read by the person who builds this.

GET /addresses

`GET` /addresses