1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
|
# cepis
Kotlin client for the [public CEP API at cep.is](https://cep.is). Official
Correios data (DNE), refreshed every two weeks.
```kotlin
import org.cepis.lookup
val address = lookup("01001-000")
println("${address.logradouro} ${address.localidade} ${address.uf}")
// Praça da Sé São Paulo SP
```
No runtime dependencies: HTTP is `java.net.http.HttpClient` from the JDK, and
the JSON and CSV readers are ~200 lines in this library — the API's payloads
are small and fixed, which is cheaper than adding `kotlinx.serialization` and
its compiler plugin to every consumer's build.
## Installation
Requires Java 17 or newer.
```kotlin
repositories {
mavenCentral()
// plus wherever you host it
}
dependencies {
implementation("org.cepis:cepis:0.1.0")
}
```
## Usage
### A single lookup
`lookup` accepts the CEP masked or unmasked and returns an `Address`:
```kotlin
val a = lookup("01310-100")
a.logradouro // "Avenida Paulista"
a.localidade // "São Paulo"
a.uf // "SP"
a.ibge // "3550308"
a.cep // "01310100" (always unmasked)
a.formattedCep // "01310-100"
```
Data fields keep the API's own Portuguese names, so what you read in the JSON
is what you access here. Only the casing is adapted where Kotlin demands it:
the API's `raio_m` is `raioM` and its `base_gerada_em` is `baseGeradaEm`.
Fields the database does not have for that CEP come back as empty strings,
never `null`. `a.raw` holds the response exactly as it arrived, so a field the
API grows before this library is updated is not lost.
### Coordinates
About 57% of CEPs have a coordinate. When they do not, `geo` is `null`:
```kotlin
a.geo?.let { geo ->
println("${geo.lat} ${geo.lon}") // -23.567202 -46.649659
println(geo.raioM) // 1084
println(geo.precisao) // "logradouro"
}
```
**Check `precisao` before computing distance.** There are two kinds of point,
and the difference between them is tens of kilometres:
| `precisao` | typical radius | what the point is |
| --- | --- | --- |
| `logradouro` | 110–140 m | the stretch of street — good for maps and distance |
| `localidade` | 7–40 km | the municipality centroid: the CEP *is* the whole city |
`geo.isPrecise` is the shorthand for `precisao == "logradouro"`:
```kotlin
val geo = a.geo
val cost =
if (geo != null && geo.isPrecise) {
shippingFrom(geo.lat, geo.lon)
} else {
shippingFromMunicipality(a.ibge)
}
```
### Many CEPs at once
Do not loop over `lookup`. Use `lookupMany`, which resolves up to 500 CEPs per
request:
```kotlin
val ceps = listOf("01001000", "99999999", "20040020")
ceps.zip(lookupMany(ceps)).forEach { (requested, address) ->
if (address == null) println("$requested: not found")
else println("$requested: ${address.localidade}")
}
```
The returned list has **the same length and the same order** as the input. A
CEP that does not exist, or is malformed, becomes `null` at its position — it
does not vanish, and it does not throw.
Lists longer than 500 are chunked automatically.
> **Batches carry no coordinate.** The endpoint behind them is CSV, and the
> CSV has no `geo` column. Every `Address` from `lookupMany` has `geo == null`,
> including for CEPs that do have one. Need `geo`? Use `lookup`, one at a time.
### API health
Useful for two things: checking the API answers, and knowing **which version
of the database** is live:
```kotlin
val h = health()
h.ok // true
h.dne // "26071" identifier of the fortnightly database
h.ceps // 1596168
h.baseGeradaEm // "2026-07-24T03:48:28Z"
```
An API reporting itself degraded does not throw — that arrives in `h.status`.
## Configuration
For anything beyond the defaults, build a `Client` and reuse it. It keeps no
state between calls and is safe to share across threads:
```kotlin
import org.cepis.Client
import java.time.Duration
val client =
Client(
baseUrl = "https://cep.is", // point at another instance
timeout = Duration.ofSeconds(10), // per attempt: connect, then response
maxAttempts = 3, // counting the first; 1 disables retrying
backoffBase = Duration.ofMillis(500), // base of the exponential wait
backoffMax = Duration.ofSeconds(8), // cap on each wait
totalTimeout = null, // cap on the whole call, attempts included
userAgent = null, // defaults to cepis-kotlin/0.1.0
)
val address = client.lookup("01001000")
```
Retries cover 429, 5xx and network failures, with exponential backoff and
jitter; 400 and 404 are never retried.
The top-level functions (`lookup`, `lookupMany`, `health`) use a shared default
client. It applies process-wide, including to third-party libraries that also
use this module. Need a different configuration? Build your own.
### Pointing at a local instance
`baseUrl` is the only parameter that usually changes between environments. The
API repo brings a local instance up with `just up`:
```kotlin
val client = Client(baseUrl = "http://localhost:8080")
```
## Errors
Everything derives from `CepisException`, a `sealed` class, so one `catch`
handles any failure and a `when` over it is exhaustive. Below that, the split
is by **the decision you have to make**, not by the HTTP status that caused it:
| error | when | does retrying help? |
| --- | --- | --- |
| `InvalidCepException` | not 8 digits | no |
| `CepNotFoundException` | well-formed, not in the database | no |
| `RateLimitedException` | 429; carries `retryAfter` | yes, later |
| `ServerErrorException` | 5xx; carries `status` | yes, later |
| `NetworkException` | DNS, connection, timeout, TLS | yes, later |
| `InvalidResponseException` | unintelligible response | probably not |
```kotlin
try {
val address = lookup(cepFromForm)
} catch (e: CepNotFoundException) {
// ask the user for another CEP
} catch (e: CepisException) {
// transient failure: reschedule
}
```
A nonsensical `Client` configuration throws a plain `IllegalArgumentException`
instead: that is a programming error, not a lookup failure.
`InvalidResponseException` almost always means something between you and the
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.
## Development
Everything runs through `make`, which shells out to the Gradle wrapper — there
is nothing to install first beyond a JDK 17:
```sh
make # list the targets
make test # run the test suite
make lint # ktlint, touches nothing
make format # apply ktlint (writes)
make build # jar + sources jar into build/libs/
make check # lint, then test, then build
```
The tests stand up a real `com.sun.net.httpserver.HttpServer` on a loopback
port and point a real `Client` at it through `baseUrl`. Nothing is mocked and
nothing touches the network.
## Licence
ISC. See [LICENSE](LICENSE).
|