How to Build a Korean Address Geocoder in 5 Minutes

#api #webdev #tutorial #korea

Korean addresses are notoriously hard to geocode. The address system changed in 2014 from a land lot system (지번 주소) to a road name system (도로명 주소), but both are still in active use. Here's how to handle both formats and get precise coordinates in minutes.

The Two Address Systems

Old system (지번 주소): Land lot based. "서울시 강남구 역삼동 123-45"
New system (도로명 주소): Road name + building number. "서울시 강남구 테헤란로 521"

Most Korean users know both addresses for their home. Delivery apps, real estate listings, and government forms use both. Your geocoder needs to handle both.

Building a Korean Address Geocoder

import requests

API_KEY = "your-api-key"
BASE_URL = "https://api.lazy-mac.com/k-address"

def geocode_korean(address: str) -> dict:
    """Geocode any Korean address format."""
    resp = requests.get(f"{BASE_URL}/geocode",
        params={"address": address, "format": "auto"},
        headers={"Authorization": f"Bearer {API_KEY}"}
    )
    result = resp.json()
    return {
        "lat": result["coordinates"]["lat"],
        "lng": result["coordinates"]["lng"],
        "normalized": result["normalized_address"],
        "address_type": result["address_type"],  # "road" or "jibun"
        "confidence": result["confidence_score"]
    }

# Works with either format
loc1 = geocode_korean("서울시 강남구 역삼동 123-45")
loc2 = geocode_korean("서울 강남구 테헤란로 521")
loc3 = geocode_korean("Seoul Gangnam-gu Teheran-ro 521")  # English OK too

Address Normalization

Before geocoding, normalize the input:

def normalize_address(raw: str) -> str:
    resp = requests.post(f"{BASE_URL}/normalize",
        json={"address": raw},
        headers={"Authorization": f"Bearer {API_KEY}"}
    )
    return resp.json()["normalized"]

# Input: "강남 역삼 123" (incomplete)
# Output: "서울특별시 강남구 역삼동 123" (normalized)

Batch Processing

For bulk address data:

addresses = ["주소1", "주소2", "주소3"]  # up to 100 per batch

resp = requests.post(f"{BASE_URL}/batch-geocode",
    json={"addresses": addresses},
    headers={"Authorization": f"Bearer {API_KEY}"}
)

results = resp.json()["results"]
for r in results:
    print(f"{r['input']} → {r['lat']}, {r['lng']} (confidence: {r['confidence']})")