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/cep_lookup.Rd | 5 ++++- man/cepis_conditions.Rd | 27 +++++++++++++++++++++++++ man/cepis_faixa.Rd | 53 +++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 84 insertions(+), 1 deletion(-) create mode 100644 man/cepis_faixa.Rd (limited to 'man') diff --git a/man/cep_lookup.Rd b/man/cep_lookup.Rd index 3c22a1e..f6f2d0b 100644 --- a/man/cep_lookup.Rd +++ b/man/cep_lookup.Rd @@ -23,7 +23,10 @@ has for it, including the coordinate when there is one. \describe{ \item{\code{cepis_invalid_cep}}{the CEP is not 8 digits. No request is made.} -\item{\code{cepis_not_found}}{well-formed, but not in the database.} +\item{\code{cepis_not_found}}{well-formed, but not in the database. Carries +\code{faixa}, a \link{cepis_faixa} naming the municipality whose range the CEP +fell into, when it fell into one. Still a not-found: the CEP does not +exist, and a \code{faixa} is not an address.} \item{\code{cepis_rate_limited}}{429 on every attempt.} \item{\code{cepis_server_error}}{5xx on every attempt.} \item{\code{cepis_network_error}}{the request never completed.} 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. +} + diff --git a/man/cepis_faixa.Rd b/man/cepis_faixa.Rd new file mode 100644 index 0000000..5d3f7ff --- /dev/null +++ b/man/cepis_faixa.Rd @@ -0,0 +1,53 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/models.R +\name{cepis_faixa} +\alias{cepis_faixa} +\title{The municipality a CEP that does not exist would have belonged to} +\description{ +The \code{faixa} field of a \link[=cepis_conditions]{cepis_not_found} condition, a +plain list of class \code{cepis_faixa}. It is \strong{context for an error, not an +address}: the CEP asked for does not exist, and nothing here says +otherwise. What it does say is which municipality owns the band of numbers +the CEP fell into. + +It exists because a CEP that fails is rarely random — it is usually +someone who knows the city and guessed the number, and the classic guess is +the \code{-000} that 957 municipalities never received. +} +\section{Fields}{ + +\describe{ +\item{\code{localidade}, \code{uf}, \code{estado}, \code{regiao}}{municipality, state code, +state name, region — the same names, and the same meaning, as in a +\link{cepis_address}.} +\item{\code{ibge}}{the municipality's IBGE code, so the answer can be joined +to other data without matching on the name.} +\item{\code{cep_ini}, \code{cep_fim}}{the smallest and the largest CEP that +\strong{actually exists} in that municipality. Not the range the Correios +publish: the DNE's own start for Areal/RJ is \code{25845000}, which is +precisely the CEP that just failed.} +\item{\code{ceps}}{how many CEPs the municipality really has.} +} +} + +\section{The range is sparse}{ + +Areal's 118 CEPs are scattered over the ~4900 numbers between \code{25845001} +and \code{25849899}. \code{cep_ini} and \code{cep_fim} are two endpoints that exist, not a +promise about anything in between — never present the pair as a list of +valid CEPs, and never iterate from one to the other. \code{ceps} is there so the +emptiness of the interval is visible: 118 out of 4899. +} + +\section{When there is no faixa}{ + +\code{NULL}, and not a list of empty strings, when the CEP falls in a band no +municipality owns. The API \strong{omits} the field rather than sending null, +and this package keeps that distinction intact: \code{is.null(x$faixa)} means +the number is close to nothing, not that the fields came back blank. + +Only \code{\link[=cep_lookup]{cep_lookup()}} reports it. In \code{\link[=cep_lookup_many]{cep_lookup_many()}} a CEP that does not +exist is still \code{NULL} at its position: the endpoint behind a batch is CSV +and says nothing about ranges. +} + -- cgit v1.3