From 3506a69f15fdf1c1c80acec26e906e6f25eeff14 Mon Sep 17 00:00:00 2001 From: Murilo Ijanc Date: Mon, 27 Jul 2026 20:38:46 -0300 Subject: Name the municipality behind a CEP that does not exist MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- src/cepis.f90 | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) (limited to 'src/cepis.f90') 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 -- cgit v1.3