diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 45 |
1 files changed, 42 insertions, 3 deletions
@@ -26,7 +26,7 @@ cd cepis-java make build ``` -That writes `build/cepis-0.1.0.jar`; put it on the classpath. +That writes `build/cepis-0.2.0.jar`; put it on the classpath. ## Usage @@ -162,7 +162,7 @@ Client client = Client.builder().baseUrl("http://localhost:8080").build(); From the command line, to confirm quickly that it answers: ```sh -java -jar build/cepis-0.1.0.jar --base-url http://localhost:8080 01001000 +java -jar build/cepis-0.2.0.jar --base-url http://localhost:8080 01001000 ``` ## Errors @@ -174,7 +174,7 @@ caused it: | error | when | does retrying help? | | --- | --- | --- | | `InvalidCepException` | not 8 digits | no | -| `CepNotFoundException` | well-formed, not in the database | no | +| `CepNotFoundException` | well-formed, not in the database; may carry `faixa()` | no | | `RateLimitedException` | 429; carries `retryAfter()` | yes, later | | `ServerErrorException` | 5xx; carries `status()` | yes, later | | `NetworkException` | DNS, connection, timeout, TLS | yes, later | @@ -198,6 +198,45 @@ more. 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. +### The municipality behind a CEP that does not exist + +A CEP that fails is rarely random: it is usually someone who knows the city and +guessed the number — the classic guess being the `-000`, which 957 +municipalities never received. So a `CepNotFoundException` may name the +municipality whose band the CEP fell in: + +```java +try { + Address address = Cepis.lookup("25845-000"); +} catch (CepNotFoundException e) { + e.faixa().ifPresent(faixa -> { + faixa.describe(); // "Areal/RJ" + faixa.localidade(); // "Areal" + faixa.ibge(); // "3300225" + faixa.cepIni(); // "25845001" + faixa.cepFim(); // "25849899" + faixa.ceps(); // 118 + }); +} +``` + +Three things to keep straight, because getting any of them wrong is worse than +not having the field at all: + +- **It is still a 404.** This is context for the error, not an address. Do not + let it turn a not-found into a success — the CEP asked for does not exist. +- **`cepIni` and `cepFim` are the smallest and the largest CEP that *actually + exist* there**, not the bounds the Correios publish. The DNE's own start for + Areal is `25845000`, which is exactly the CEP that just failed. +- **The interval is sparse.** Areal's 118 CEPs are spread over some 9000 + numbers, so almost nothing between the two exists. That is what `ceps()` is + for. Never present the pair as a range, or a list, of valid CEPs. + +`faixa()` is empty whenever the CEP fell in a band no municipality owns; the API +omits the field in that case rather than sending null. A `faixa` that is +malformed, empty or of the wrong shape is dropped the same way: the not-found +itself is never at risk of becoming a parse failure. + ## Development Everything runs through `make` and the JDK. There is nothing to install first |