{"openapi":"3.0.0","paths":{"/v1/health":{"get":{"operationId":"HealthController_check","parameters":[],"responses":{"200":{"description":""}},"tags":["health"]}},"/v1/regions":{"get":{"operationId":"getRegions","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegionsResponseDto"}}}}},"summary":"Regiones de Chile con sus comunas","tags":["postal"]}},"/v1/postal-codes/search":{"get":{"description":"Usa la caché local y, ante una dirección completa desconocida, consulta la fuente oficial. Si solo hay dato a nivel de comuna o la consulta falla temporalmente, devuelve el código base. `precision`, `source` y `addressStatus` explican el resultado.","operationId":"searchPostalCode","parameters":[{"name":"commune","required":true,"in":"query","description":"Nombre de la comuna","schema":{"example":"Ñuñoa","type":"string"}},{"name":"street","required":false,"in":"query","description":"Calle","schema":{"example":"Av. Irarrázaval","type":"string"}},{"name":"number","required":false,"in":"query","description":"Número","schema":{"example":"3400","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResultDto"}}}},"400":{"description":"Parámetros inválidos"},"404":{"description":"Comuna no encontrada"}},"summary":"Busca el código postal por comuna (y opcionalmente calle + número)","tags":["postal"]}},"/v1/reverse":{"get":{"description":"Reverse-geocoding server-side (Nominatim + Overpass) para autocompletar la dirección desde el GPS. Best-effort: cualquier campo puede venir null.","operationId":"reverseGeocode","parameters":[{"name":"lat","required":true,"in":"query","description":"Latitud (dentro de Chile)","schema":{"example":-33.414,"type":"number"}},{"name":"lon","required":true,"in":"query","description":"Longitud (dentro de Chile)","schema":{"example":-70.5957,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReverseResultDto"}}}},"400":{"description":"Coordenadas inválidas o fuera de Chile"}},"summary":"Comuna + calle + número desde coordenadas (vía OpenStreetMap)","tags":["postal"]}},"/v1/stats/summary":{"get":{"operationId":"getStats","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatsDto"}}}}},"summary":"Conteos de cobertura de datos","tags":["postal"]}}},"info":{"title":"MiCodigoPostal.Fun API","description":"API pública y gratuita del código postal de Chile por comuna y dirección. Caché propia + datos abiertos, sin API key. `precision` indica si es nivel comuna o manzana y `addressStatus` explica el resultado de la dirección.","version":"1.0.0","contact":{"name":"KaiNext","url":"https://www.kainext.cl","email":""},"license":{"name":"MIT","url":"https://opensource.org/licenses/MIT"}},"tags":[{"name":"postal","description":"Búsqueda de códigos postales"},{"name":"health","description":"Estado del servicio"}],"servers":[],"components":{"schemas":{"CommuneItemDto":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","example":"Puente Alto"}},"required":["id","name"]},"RegionDto":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string","example":"12"},"name":{"type":"string","example":"Región Metropolitana"},"communes":{"type":"array","items":{"$ref":"#/components/schemas/CommuneItemDto"}}},"required":["id","code","name","communes"]},"RegionsResponseDto":{"type":"object","properties":{"regions":{"type":"array","items":{"$ref":"#/components/schemas/RegionDto"}}},"required":["regions"]},"SearchResultDto":{"type":"object","properties":{"code":{"type":"string","example":"8150000","description":"7-digit Chilean postal code"},"precision":{"type":"string","example":"comuna","enum":["comuna","exacta"],"description":"'comuna' = commune base code; 'exacta' = full address-level code"},"addressStatus":{"type":"string","example":"commune_only","enum":["not_requested","exact","commune_only","temporarily_unavailable"],"description":"Outcome of the full-address lookup: not requested, exact, commune-only response, or temporary upstream failure"},"source":{"type":"string","example":"base","enum":["base","osm","official"],"description":"'base' = commune; 'osm' = OpenStreetMap; 'official' = authoritative validation"},"pointSource":{"type":"string","example":"address","enum":["address","commune"],"description":"What lat/lon locate: 'address' = the address itself; 'commune' = only its commune centroid, which is where they fall back when no address-level coordinates are on record"},"commune":{"type":"string","example":"Puente Alto"},"province":{"type":"object","example":"Provincia de Cordillera","nullable":true},"region":{"type":"string","example":"Región Metropolitana"},"lat":{"type":"object","example":-33.591,"nullable":true},"lon":{"type":"object","example":-70.5575,"nullable":true}},"required":["code","precision","addressStatus","source","pointSource","commune","province","region","lat","lon"]},"ReverseResultDto":{"type":"object","properties":{"commune":{"type":"object","example":"Las Condes","nullable":true,"description":"Matched commune, or null if none resolved"},"street":{"type":"object","example":"Isidora Goyenechea","nullable":true},"number":{"type":"object","example":"3356","nullable":true}},"required":["commune","street","number"]},"StatsDto":{"type":"object","properties":{"regions":{"type":"number","example":16},"communes":{"type":"number","example":346},"exactAddresses":{"type":"number","example":960,"description":"Address-level codes validated against the official registry. Inherited, unvalidated codes are not counted."}},"required":["regions","communes","exactAddresses"]}}}}