From 399eac351b1bc29d5047dbac96486c281be1b05c Mon Sep 17 00:00:00 2001 From: Murilo Ijanc Date: Mon, 27 Jul 2026 20:38:27 -0300 Subject: Report the municipality a missing CEP would have belonged to A CEP that fails a lookup is rarely a random number: it is usually someone who knows the city and guessed, and the classic guess is the -000 that 957 municipalities never received. The API now answers those 404s with a faixa naming the municipality that owns the band the number fell into, which is the difference between telling a user "invalid CEP" and "no such CEP in Areal/RJ". It is context for an error and never an address, so it rides on the cepis_not_found condition instead of turning the failure into a success, and cep_ini/cep_fim are the endpoints that exist rather than the range the Correios publish - the interval between them is sparse, which is what ceps counts. Parsing is deliberately unable to signal: a faixa that is null, an array, a string or half a body leaves a clean not-found behind, because the caller asked for the CEP, not for the decoration on its absence. --- man/cepis_conditions.Rd | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) (limited to 'man/cepis_conditions.Rd') diff --git a/man/cepis_conditions.Rd b/man/cepis_conditions.Rd index 4def4ff..9b25cbe 100644 --- a/man/cepis_conditions.Rd +++ b/man/cepis_conditions.Rd @@ -40,3 +40,30 @@ API is answering instead of it — a captive Wi-Fi portal, a corporate proxy, an HTML error page. Useful as a diagnosis: the problem is not in your code. } +\section{What cepis_not_found carries}{ + +\code{cep}, the 8 digits as they went to the API, and \code{faixa}: a \link{cepis_faixa} +naming the municipality that owns the band of numbers the CEP fell into, +or \code{NULL} when it fell in a band nobody owns. The API omits it, it never +sends null, so \code{NULL} here is the same statement. + +It changes nothing about the answer — the CEP still does not exist, and a +\code{faixa} is not an address — but it is usually the difference between +telling someone "invalid CEP" and telling them "no such CEP in Areal/RJ": + +\if{html}{\out{
}}\preformatted{tryCatch( + cep_lookup("25845000"), + cepis_not_found = function(e) \{ + if (is.null(e$faixa)) \{ + "no such CEP" + \} else \{ + paste0("no such CEP in ", e$faixa$localidade, "/", e$faixa$uf) + \} + \} +) +}\if{html}{\out{
}} + +The CEP that failed above is the DNE's own first number for Areal, and it +is the shape of guess this field is for. +} + -- cgit v1.3