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
|
# cepis
Common Lisp client for the [public CEP API at cep.is](https://cep.is).
Official Correios data (DNE), refreshed every two weeks. Developed and tested
on SBCL.
```lisp
(let ((address (cepis:lookup "01001-000")))
(format t "~a ~a ~a~%"
(cepis:address-logradouro address)
(cepis:address-localidade address)
(cepis:address-uf address)))
;; Praça da Sé São Paulo SP
```
## Installation
Clone it where ASDF can find it, for instance `~/common-lisp/`, then load it
with Quicklisp so the dependencies come along:
```sh
git clone https://git.cep.is/lisp.git ~/common-lisp/cepis
```
```lisp
(ql:quickload "cepis")
```
Three dependencies:
[`dexador`](https://github.com/fukamachi/dexador) for HTTP, because the
standard has no client and dexador is the maintained, synchronous, TLS-capable
one; [`com.inuoe.jzon`](https://github.com/Zulu-Inuoe/jzon) for JSON, because
it is the strictest of the current parsers and does not invent its own reader
syntax; and [`babel`](https://github.com/cl-babel/babel) to decode UTF-8
bodies. The batch endpoint's CSV is read by a small RFC 4180 reader included
here — less total weight than pulling a CSV library in for one call.
## Usage
### A single lookup
`lookup` accepts the CEP masked or unmasked and returns an `address`:
```lisp
(defvar *a* (cepis:lookup "01310-100"))
(cepis:address-logradouro *a*) ; "Avenida Paulista"
(cepis:address-localidade *a*) ; "São Paulo"
(cepis:address-uf *a*) ; "SP"
(cepis:address-ibge *a*) ; "3550308"
(cepis:address-cep *a*) ; "01310100" (always unmasked)
(cepis:address-formatted-cep *a*) ; "01310-100"
```
Fields the database does not have for that CEP come back as empty strings,
never `nil`. The slot names are the API's own, in Portuguese, with Lisp's
hyphenation where the JSON has an underscore: `raio_m` is read with
`geo-raio-m`.
### Coordinates
About 57% of CEPs have a coordinate. When they do not, `address-geo` is `nil`:
```lisp
(let ((geo (cepis:address-geo *a*)))
(when geo
(list (cepis:geo-lat geo) ; -23.567202d0
(cepis:geo-lon geo) ; -46.649659d0
(cepis:geo-raio-m geo) ; 1084
(cepis:geo-precisao geo)))) ; "logradouro"
```
**Check `geo-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-precise-p` is the shorthand for `precisao` being `"logradouro"`:
```lisp
(let ((geo (cepis:address-geo *a*)))
(if (and geo (cepis:geo-precise-p geo))
(shipping-from (cepis:geo-lat geo) (cepis:geo-lon geo))
(shipping-from-municipality (cepis:address-ibge *a*))))
```
### Many CEPs at once
Do not loop over `lookup`. Use `lookup-many`, which resolves up to 500 CEPs
per request:
```lisp
(let ((ceps '("01001000" "99999999" "20040020")))
(loop for cep in ceps
for address in (cepis:lookup-many ceps)
do (format t "~a: ~a~%"
cep
(if address (cepis:address-localidade address) "not found"))))
```
The returned list has **the same length and the same order** as the input. A
CEP that does not exist, or is malformed, is `nil` at its position — it does
not vanish, and it does not signal.
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 `lookup-many` has
> `address-geo` of `nil`, including for CEPs that do have one. Need the
> coordinate? 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:
```lisp
(let ((h (cepis:health)))
(cepis:health-ok-p h) ; T
(cepis:health-dne h) ; "26071" identifier of the fortnightly database
(cepis:health-ceps h) ; 1596168
(cepis:health-base-gerada-em h)); "2026-07-24T03:48:28Z"
```
An API reporting itself degraded does not signal — that arrives in
`health-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:
```lisp
(defvar *cep*
(cepis:make-client
:base-url "https://cep.is" ; point at another instance
:timeout 10.0 ; seconds per socket operation
:max-attempts 3 ; counting the first; 1 disables retrying
:backoff-base 0.5 ; base of the exponential wait
:backoff-max 8.0 ; cap on each wait
:total-timeout nil)) ; cap on the whole call, attempts included
(cepis:lookup "01001000" :client *cep*)
```
Retries cover 429, 5xx and network failures, with exponential backoff and
jitter; 400 and 404 are never retried. `timeout` bounds each socket operation,
not the whole call — that is what `total-timeout` is for. See the docstring of
`make-client` for the details of each parameter.
`lookup`, `lookup-many` and `health` use the shared client in `cepis:*client*`
when no `:client` is given. Do not mutate it: it applies process-wide,
including to third-party libraries that also use this package. Need a
different configuration? Build your own.
### Pointing at a local instance
`base-url` is the only parameter that usually changes between environments.
The API repo brings a local instance up with `just up`:
```lisp
(cepis:make-client :base-url "http://localhost:8080")
```
## Errors
Everything derives from `cepis-error`, so one handler catches any failure.
Below that, the split is by **the decision you have to make**, not by the HTTP
status that caused it:
| condition | when | does retrying help? |
| --- | --- | --- |
| `invalid-cep` | not 8 digits | no |
| `cep-not-found` | well-formed, not in the database | no |
| `rate-limited` | 429 | yes, later |
| `server-error` | 5xx | yes, later |
| `network-error` | DNS, connection, timeout, TLS | yes, later |
| `invalid-response` | unintelligible response | probably not |
```lisp
(handler-case (cepis:lookup cep-from-form)
(cepis:cep-not-found ()
:ask-for-another-cep)
(cepis:cepis-error ()
:reschedule))
```
`error-message` returns the description of any of them; `server-error-status`
and `rate-limited-retry-after` carry the extra facts their callers need.
`invalid-cep` is also a `parse-error` and `cep-not-found` a `cell-error`, so
code already handling those standard types during input validation keeps
working without knowing this library exists — and `cell-error-name` gives back
the CEP that was not found.
`invalid-response` 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 drives SBCL in script mode. Quicklisp
must be installed and loaded from your `~/.sbclrc`:
```sh
make # list the targets
make test # run the suite
make lint # recompile from scratch, failing on any warning
make build # compile and load the library
make check # lint, then test, then build
```
The suite stands up a real HTTP server on a loopback port and points a client
at it with `:base-url`. Nothing is stubbed and no test touches the network.
## Licence
ISC. See [LICENSE](LICENSE).
|