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_faixa.Rd | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 man/cepis_faixa.Rd (limited to 'man/cepis_faixa.Rd') 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