{"openapi":"3.0.3","info":{"title":"Korean Address Validator API","version":"2.0.0","description":"Parse, validate, normalize, and geocode Korean addresses. Works offline with built-in administrative division data. Supports road addresses (도로명) and lot-number addresses (지번). Optional Juso.go.kr key upgrades accuracy.","contact":{"url":"https://api.lazy-mac.com/korean-address-validator"}},"servers":[{"url":"https://api.lazy-mac.com/korean-address-validator"}],"paths":{"/":{"get":{"summary":"API info","operationId":"getInfo","responses":{"200":{"description":"Service info or HTML landing page","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"string"},"endpoints":{"type":"object"}}}}}}}}},"/health":{"get":{"summary":"Health check","operationId":"healthCheck","responses":{"200":{"description":"Service health","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"service":{"type":"string"},"version":{"type":"string"},"ts":{"type":"string","format":"date-time"}}}}}}}}},"/validate":{"get":{"summary":"Validate a Korean address","description":"Parses and validates a Korean address string. Returns components (sido/sigungu/dong), confidence score (0-100), type (road/jibun/partial), and detected issues.","operationId":"validateAddress","parameters":[{"name":"address","in":"query","required":true,"description":"Korean address to validate (e.g. 서울특별시 강남구 테헤란로 152)","schema":{"type":"string","example":"서울특별시 강남구 테헤란로 152"}}],"responses":{"200":{"description":"Validation result","content":{"application/json":{"schema":{"type":"object","properties":{"valid":{"type":"boolean"},"score":{"type":"integer","minimum":0,"maximum":100},"input":{"type":"string"},"normalized":{"type":"string"},"components":{"type":"object","properties":{"sido":{"type":"string","nullable":true},"sigungu":{"type":"string","nullable":true},"eupmyeondong":{"type":"string","nullable":true},"detail":{"type":"string","nullable":true},"roadAddress":{"type":"string","nullable":true},"jibunAddress":{"type":"string","nullable":true}}},"type":{"type":"string","enum":["road","jibun","partial","unknown"]},"postalCode":{"type":"string","nullable":true},"coordinates":{"type":"object","nullable":true,"properties":{"lat":{"type":"number"},"lng":{"type":"number"}}},"confidence":{"type":"string","enum":["high","medium","low"]},"issues":{"type":"array","items":{"type":"string"},"nullable":true},"source":{"type":"string"}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/normalize":{"get":{"summary":"Normalize a Korean address","description":"Expands abbreviations and reorders components into canonical form (시/도 + 시/군/구 + 읍/면/동 + detail). Accepts abbreviated forms like 서울 강남구 or 경기 수원시.","operationId":"normalizeAddress","parameters":[{"name":"address","in":"query","required":true,"description":"Korean address to normalize (abbreviated or partial form accepted)","schema":{"type":"string","example":"서울 강남구 역삼동 123"}}],"responses":{"200":{"description":"Normalization result","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"input":{"type":"string"},"normalized":{"type":"string"},"changed":{"type":"boolean"},"changes":{"type":"array","items":{"type":"object"}},"components":{"type":"object"},"completeness":{"type":"integer"}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/search":{"get":{"summary":"Search Korean addresses","description":"Search across Korean administrative divisions (시/도, 시/군/구). Returns matching divisions with postal code estimates and centroid coordinates.","operationId":"searchAddresses","parameters":[{"name":"q","in":"query","required":true,"description":"Search query (Korean administrative division name)","schema":{"type":"string","example":"강남"}},{"name":"limit","in":"query","required":false,"description":"Maximum results to return (1-50, default 10)","schema":{"type":"integer","minimum":1,"maximum":50,"default":10}}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"query":{"type":"string"},"count":{"type":"integer"},"results":{"type":"array","items":{"type":"object","properties":{"address":{"type":"string"},"type":{"type":"string"},"components":{"type":"object"},"postalCode":{"type":"string","nullable":true},"coordinates":{"type":"object","nullable":true},"confidence":{"type":"string"}}}}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/geocode":{"get":{"summary":"Geocode a Korean address","description":"Returns centroid coordinates for a Korean address. Accuracy is at the district level (시/군/구). Street-level accuracy requires JUSO_API_KEY.","operationId":"geocodeAddress","parameters":[{"name":"address","in":"query","required":true,"description":"Korean address to geocode","schema":{"type":"string","example":"부산광역시 해운대구 우동"}}],"responses":{"200":{"description":"Geocoding result","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"input":{"type":"string"},"normalized":{"type":"string"},"coordinates":{"type":"object","properties":{"lat":{"type":"number"},"lng":{"type":"number"}}},"accuracy":{"type":"string","enum":["province","district"]},"components":{"type":"object"},"source":{"type":"string"}}}}}},"400":{"description":"Invalid input or could not determine location","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/mcp":{"get":{"summary":"MCP endpoint info","operationId":"mcpInfo","responses":{"200":{"description":"MCP endpoint information","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"summary":"MCP JSON-RPC 2.0","operationId":"mcpEndpoint","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"method":{"type":"string"},"id":{"type":"integer"},"params":{"type":"object"}},"required":["jsonrpc","method"]}}}},"responses":{"200":{"description":"JSON-RPC response","content":{"application/json":{"schema":{"type":"object"}}}}}}}},"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"X-API-Key"}}}}