Report the municipality a missing CEP would have belonged toHEADv0.2.0main

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.

3 files changed, 84 insertions, 1 deletions

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{<div class="sourceCode r">}}\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{</div>}}
+
+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.
+}
+