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
|
# cepis
Elixir client for the [public CEP API at cep.is](https://cep.is). Official
Correios data (DNE), refreshed every two weeks.
```elixir
{:ok, address} = Cepis.lookup("01001-000")
{address.logradouro, address.localidade, address.uf}
# {"Praça da Sé", "São Paulo", "SP"}
```
## Installation
```elixir
def deps do
[{:cepis, git: "https://git.cep.is/elixir.git", tag: "v0.1.0"}]
end
```
No dependencies. Requires Elixir 1.14 or newer and Erlang/OTP 27 or newer —
HTTP is `:httpc` and JSON is the `:json` module, both from the standard
distribution.
## Usage
Every function returns `{:ok, result}` or `{:error, error}`, and every one has
a bang variant that returns the result directly and raises instead.
### A single lookup
`lookup/2` accepts the CEP masked or unmasked and returns a `Cepis.Address`:
```elixir
{:ok, a} = Cepis.lookup("01310-100")
a.logradouro # "Avenida Paulista"
a.localidade # "São Paulo"
a.uf # "SP"
a.ibge # "3550308"
a.cep # "01310100" (always unmasked)
Cepis.Address.formatted_cep(a) # "01310-100"
```
Field names are the API's own, in Portuguese. Fields the database does not have
for that CEP come back as empty strings, never `nil`.
### Coordinates
About 57% of CEPs have a coordinate. When they do not, `geo` is `nil`:
```elixir
{:ok, a} = Cepis.lookup("01310100")
if a.geo do
a.geo.lat # -23.567202
a.geo.lon # -46.649659
a.geo.raio_m # 1084
a.geo.precisao # "logradouro"
end
```
**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 |
`Cepis.Geo.precise?/1` is the shorthand for `precisao == "logradouro"`:
```elixir
if a.geo && Cepis.Geo.precise?(a.geo) do
shipping_from(a.geo.lat, a.geo.lon)
else
shipping_from_municipality(a.ibge)
end
```
### Many CEPs at once
Do not loop over `lookup/2`. Use `lookup_many/2`, which resolves up to 500 CEPs
per request:
```elixir
ceps = ["01001000", "99999999", "20040020"]
{:ok, addresses} = Cepis.lookup_many(ceps)
for {requested, address} <- Enum.zip(ceps, addresses) do
case address do
nil -> IO.puts("#{requested}: not found")
a -> IO.puts("#{requested}: #{a.localidade}")
end
end
```
The returned list has **the same length and the same order** as the input. A
CEP that does not exist, or is malformed, becomes `nil` at its position — it
does not vanish, and it does not fail the call.
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 `Cepis.Address` from `lookup_many/2` has
> `geo: nil`, including for CEPs that do have one. Need `geo`? Use `lookup/2`,
> one at a time.
### API health
Useful for two things: checking the API answers, and knowing **which version of
the database** is live:
```elixir
{:ok, h} = Cepis.health()
Cepis.Health.ok?(h) # true
h.dne # "26071" identifier of the fortnightly database
h.ceps # 1596168
h.base_gerada_em # "2026-07-24T03:48:28Z"
```
An API reporting itself degraded is not a failure — that arrives in `h.status`.
## Configuration
The last argument of every call is the configuration: a keyword list, or a
`Cepis.Client` built once with `Cepis.Client.new/1` and reused. It is plain
data with no process behind it, so it is safe to share across processes.
```elixir
client =
Cepis.Client.new(
base_url: "https://cep.is", # point at another instance
timeout: 10_000, # milliseconds for one attempt
max_attempts: 3, # counting the first; 1 disables retrying
backoff_base: 500, # base of the exponential wait
backoff_max: 8_000, # cap on each wait
total_timeout: nil # cap on the whole call, attempts included
)
{:ok, address} = Cepis.lookup("01001000", client)
```
All durations are in milliseconds. Retries cover 429, 5xx and network failures,
with exponential backoff and jitter; 400 and 404 are never retried. See
`Cepis.Client` for the details of each option.
### Pointing at a local instance
`base_url` is the only option that usually changes between environments. The
API repo brings a local instance up with `just up`:
```elixir
Cepis.lookup("01001000", base_url: "http://localhost:8080")
```
## Errors
Matching on `{:error, error}` is the one handler that catches everything. 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? |
| --- | --- | --- |
| `Cepis.InvalidCEPError` | not 8 digits | no |
| `Cepis.NotFoundError` | well-formed, not in the database | no |
| `Cepis.RateLimitError` | 429 | yes, later |
| `Cepis.ServerError` | 5xx | yes, later |
| `Cepis.NetworkError` | DNS, connection, timeout, TLS | yes, later |
| `Cepis.InvalidResponseError` | unintelligible response | probably not |
```elixir
case Cepis.lookup(cep_from_form) do
{:ok, address} -> address
{:error, %Cepis.NotFoundError{}} -> ask_for_another_cep()
{:error, error} -> reschedule(error)
end
```
`Cepis.Error.retriable?/1` answers the same question in code.
`Cepis.RateLimitError` exposes `retry_after` in milliseconds, ready for
`Process.send_after/3`.
`Cepis.InvalidResponseError` 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 `mix`:
```sh
make # list the targets
make test # run the ExUnit suite
make lint # mix format --check-formatted, touches nothing
make format # apply mix format
make build # compile with warnings as errors
make check # lint, then test, then build
```
## Licence
ISC. See [LICENSE](LICENSE).
|