Name the municipality behind a CEP that does not existHEADv0.2.0main

A CEP that fails 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. Answering that with a bare "not
found" throws away what the API already knows: which municipality the
number would have fallen under.

The 404 now carries an optional faixa, and it is exposed the way geo
already is — a derived type behind a logical flag on the address, because
the API omits the block entirely rather than sending null. It stays a
404: found is still false and the status is still CEPIS_ERR_NOT_FOUND.
The band is context for the failure, never an address.

cep_ini and cep_fim are the smallest and largest CEP that actually exist
there, not the bounds the Correios publish — the published start for
Areal is 25845000, exactly the CEP that fails. The pair is not a list
either: 118 CEPs over some 4,900 numbers, which is what ceps is for.

Parsing is deliberately silent about every failure. A body that is not
JSON, or a faixa that is absent, null, not an object or empty, leaves
has_faixa false. Turning any of those into an invalid-response error
would tell the caller to retry a CEP that will never exist.

1 files changed, 16 insertions, 2 deletions

diff --git a/src/cepis.f90 b/src/cepis.f90
index 27e2c6d..2c4f687 100644
--- a/src/cepis.f90
+++ b/src/cepis.f90
@@ -43,6 +43,7 @@ module cepis
     public :: cepis_status_name
 
     public :: cepis_geo
+    public :: cepis_faixa
     public :: cepis_address
     public :: cepis_health
     public :: cepis_client
@@ -55,7 +56,7 @@ module cepis
     public :: cepis_format_cep
 
     !> Library version.
-    character(len=*), parameter, public :: CEPIS_VERSION = '0.1.0'
+    character(len=*), parameter, public :: CEPIS_VERSION = '0.2.0'
 
     !> Default API endpoint.
     character(len=*), parameter, public :: CEPIS_DEFAULT_BASE_URL = 'https://cep.is'
@@ -286,6 +287,12 @@ contains
     !> server knows something this client does not.
     !>
     !> This is the only call that carries `has_geo` and `geo`.
+    !>
+    !> A 404 is `CEPIS_ERR_NOT_FOUND` and `address%found` stays `.false.`, but
+    !> the API may still say which municipality the CEP *would* have belonged
+    !> to. When it does, `address%has_faixa` is `.true.` and `address%faixa`
+    !> names it — see `cepis_faixa`. It is context for the failure, never an
+    !> address: the call still failed and the CEP still does not exist.
     subroutine client_lookup(self, cep, address, status, message, http_status, retry_after)
         class(cepis_client), intent(in) :: self
         character(len=*), intent(in) :: cep
@@ -315,6 +322,11 @@ contains
         if (response%status == 404) then
             status = CEPIS_ERR_NOT_FOUND
             message = 'CEP '//digits//' does not exist in the DNE database'
+            call address_faixa_from_body(response%body, address)
+            if (address%has_faixa) then
+                message = message//' — its band belongs to '//address%faixa%localidade
+                if (len(address%faixa%uf) > 0) message = message//'/'//address%faixa%uf
+            end if
             return
         end if
 
@@ -355,7 +367,9 @@ contains
     !> **The batch carries no coordinate.** The endpoint behind it is CSV, and
     !> the CSV has no `geo` column. Every address returned here has
     !> `has_geo = .false.`, including for CEPs that do have one. Need `geo`?
-    !> Use `lookup`, one at a time.
+    !> Use `lookup`, one at a time. The same goes for `has_faixa`: the CSV has
+    !> no `faixa` column either, so a CEP the batch did not resolve is simply
+    !> `found = .false.` with nothing said about where it would have been.
     subroutine client_lookup_many(self, ceps, addresses, status, message, &
                                   http_status, retry_after)
         class(cepis_client), intent(in) :: self