diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 57 |
1 files changed, 56 insertions, 1 deletions
@@ -167,7 +167,7 @@ Failures are classed conditions. Everything inherits `cepis_error` (and | class | when | does retrying help? | | --- | --- | --- | | `cepis_invalid_cep` | not 8 digits | no | -| `cepis_not_found` | well-formed, not in the database | no | +| `cepis_not_found` | well-formed, not in the database; carries `faixa` | no | | `cepis_rate_limited` | 429; carries `retry_after` | yes, later | | `cepis_server_error` | 5xx; carries `status` | yes, later | | `cepis_network_error` | DNS, connection, timeout, TLS | yes, later | @@ -185,6 +185,61 @@ tryCatch( 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. +### Where a CEP that does not exist would have been + +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 `-000` that 957 +municipalities never received. When the number falls inside the range of a +municipality, `cepis_not_found` carries a `faixa` naming it: + +```r +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) + } + } +) +#> "no such CEP in Areal/RJ" +``` + +The lookup **still failed**, and a `faixa` is not an address — it is context +for the error, and answers "did you mean somewhere in Areal?" instead of +"invalid CEP". The condition is the same `cepis_not_found` as before; code +that ignores `faixa` keeps working. + +```r +f <- e$faixa + +f$localidade # "Areal" +f$uf # "RJ" +f$estado # "Rio de Janeiro" +f$regiao # "Sudeste" +f$ibge # "3300225" +f$cep_ini # "25845001" +f$cep_fim # "25849899" +f$ceps # 118 +``` + +Two things about `cep_ini` and `cep_fim`: + +- They are the smallest and the largest CEP that **actually exist** there, + not the range the Correios publish. The DNE's own start for Areal is + `25845000` — exactly the CEP that just failed above. +- **The range is sparse.** Areal's 118 CEPs are scattered over the ~4900 + numbers between the two endpoints. `ceps` is there so that is visible: + never present the pair as a list of valid CEPs, and never iterate from one + to the other. + +`faixa` is `NULL` when the CEP falls in a band no municipality owns. The API +omits the field rather than sending null, so `is.null(e$faixa)` says the +number is close to nothing, not that the fields came back blank. Batches do +not report it either: `cep_lookup_many()` still gives `NULL` at that +position, because the endpoint behind it is CSV. + ## Development Everything runs through `make`: |