From 218bc8fbfbbdc2520130ef43652a6cd22a6e67fb Mon Sep 17 00:00:00 2001
From: Murilo Ijanc <murilo@ijanc.org>
Date: Mon, 27 Jul 2026 20:42:18 -0300
Subject: Carry the municipality range on a not-found CEP
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A CEP that fails a lookup is rarely a random number. It is usually
someone who knows the city and guessed the digits, and the classic guess
is the -000 that 957 municipalities never received. The API now answers
those 404s with a faixa naming the municipality whose band the number
falls into, so a caller can ask "did you mean somewhere in Areal/RJ?"
instead of returning a bare "not found".

Cep_not_found becomes an inline record so the context rides along with
the message, matching how Rate_limited and Server_error already carry
theirs. It is still a 404: faixa is context on the failure and never
promotes it to an address, and its bounds are the smallest and largest
CEP that actually exist there — sparse across the interval, which is
what the ceps count is for — not the bounds the Correios publish.

Parsing is deliberately lenient. A missing, null, malformed or
municipality-less faixa yields None rather than an error: a 404 is a
clean answer, and no shape of this field should turn it into an
Invalid_response.
---
 lib/cepis.ml | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 51 insertions(+), 6 deletions(-)

(limited to 'lib/cepis.ml')

diff --git a/lib/cepis.ml b/lib/cepis.ml
index a168d37..be69f2e 100644
--- a/lib/cepis.ml
+++ b/lib/cepis.ml
@@ -1,4 +1,4 @@
-let version = "0.1.0"
+let version = "0.2.0"
 let default_url = "https://cep.is"
 let max_batch = 500
 
@@ -39,21 +39,38 @@ type health = {
 
 let is_ok h = String.equal h.status "ok"
 
+type faixa = {
+  localidade : string;
+  uf : string;
+  estado : string;
+  regiao : string;
+  ibge : string;
+  cep_ini : string;
+  cep_fim : string;
+  ceps : int;
+}
+
 type error =
   | Invalid_cep of string
-  | Cep_not_found of string
+  | Cep_not_found of { message : string; faixa : faixa option }
   | Rate_limited of { message : string; retry_after : float option }
   | Server_error of { message : string; status : int }
   | Network_error of string
   | Invalid_response of string
 
 let error_message = function
-  | Invalid_cep m | Cep_not_found m | Network_error m | Invalid_response m -> m
-  | Rate_limited { message; _ } | Server_error { message; _ } -> message
+  | Invalid_cep m | Network_error m | Invalid_response m -> m
+  | Cep_not_found { message; _ }
+  | Rate_limited { message; _ }
+  | Server_error { message; _ } ->
+      message
 
 let string_of_error = function
   | Invalid_cep m -> "invalid CEP: " ^ m
-  | Cep_not_found m -> "CEP not found: " ^ m
+  | Cep_not_found { message; faixa = None } -> "CEP not found: " ^ message
+  | Cep_not_found { message; faixa = Some f } ->
+      Printf.sprintf "CEP not found: %s (that number falls in %s/%s)" message
+        f.localidade f.uf
   | Rate_limited { message; retry_after = Some s } ->
       Printf.sprintf "rate limited (retry after %gs): %s" s message
   | Rate_limited { message; retry_after = None } -> "rate limited: " ^ message
@@ -125,6 +142,24 @@ let geo_of_json = function
       | _ -> None)
   | _ -> None
 
+let faixa_of_json : Yojson.Safe.t -> faixa option = function
+  | `Assoc fields -> (
+      match string_field fields "localidade" with
+      | "" -> None
+      | localidade ->
+          Some
+            {
+              localidade;
+              uf = string_field fields "uf";
+              estado = string_field fields "estado";
+              regiao = string_field fields "regiao";
+              ibge = string_field fields "ibge";
+              cep_ini = string_field fields "cep_ini";
+              cep_fim = string_field fields "cep_fim";
+              ceps = int_field fields "ceps";
+            })
+  | _ -> None
+
 let address_of_fields fields =
   {
     cep = string_field fields "cep";
@@ -190,6 +225,12 @@ let api_message body fallback =
   | _ -> fallback
   | exception _ -> fallback
 
+let faixa_of_body body =
+  match Yojson.Safe.from_string body with
+  | `Assoc fields -> faixa_of_json (field fields "faixa")
+  | _ -> None
+  | exception _ -> None
+
 let months =
   [|
     "jan";
@@ -481,7 +522,11 @@ module Client = struct
     if code = 404 then
       Error
         (Cep_not_found
-           (Printf.sprintf "CEP %s does not exist in the DNE database" number))
+           {
+             message =
+               Printf.sprintf "CEP %s does not exist in the DNE database" number;
+             faixa = faixa_of_body body;
+           })
     else if code = 400 then
       Error
         (Invalid_cep
-- 
cgit v1.3