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. --- DESCRIPTION | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) (limited to 'DESCRIPTION') diff --git a/DESCRIPTION b/DESCRIPTION index c6eb473..801e741 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,6 +1,6 @@ Package: cepis Title: Client for the Public CEP API at cep.is -Version: 0.1.0 +Version: 0.2.0 Authors@R: person("Murilo", "Ijanc", email = "murilo@ijanc.org", role = c("aut", "cre")) @@ -8,9 +8,10 @@ Description: Looks up Brazilian postal codes (CEP) against the public API at , which serves official Correios data (DNE) refreshed every two weeks. Resolves a single CEP, batches of up to 500 per request with the order preserved, the coordinate the database has for about 57% - of them, and the API's health. Retries transient failures with - exponentially backed-off, jittered waits and never retries a definitive - answer. + of them, and the API's health. A CEP that does not exist reports the + municipality whose range it fell into, when it fell into one. Retries + transient failures with exponentially backed-off, jittered waits and + never retries a definitive answer. License: file LICENSE URL: https://cep.is Encoding: UTF-8 -- cgit v1.3