# 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).