# Cepis

Swift client for the [public CEP API at cep.is](https://cep.is). Official
Correios data (DNE), refreshed every two weeks.

```swift
import Cepis

let address = try await Client.shared.lookup("01001-000")
print(address.logradouro, address.localidade, address.uf)
// Praça da Sé São Paulo SP
```

No dependencies: `URLSession` and `Codable` from the standard library and
Foundation.

## Installation

Add the package to `Package.swift`:

```swift
dependencies: [
    .package(url: "https://git.cep.is/swift.git", from: "0.1.0")
]
```

and the product to your target:

```swift
.target(name: "MyTarget", dependencies: [.product(name: "Cepis", package: "swift")])
```

Requires Swift 5.9 or newer. Runs on macOS 10.15+, iOS 13+ and Linux.

## Usage

### A single lookup

`lookup` accepts the CEP masked or unmasked and returns an `Address`:

```swift
let a = try await Client.shared.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"
```

The data fields keep the API's Portuguese names; only the casing follows Swift
convention. 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`:

```swift
if let geo = a.geo {
    print(geo.lat, geo.lon)  // -23.567202 -46.649659
    print(geo.raioM)         // 1084   (JSON `raio_m`)
    print(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"`:

```swift
if let geo = a.geo, geo.isPrecise {
    cost = shipping(from: geo.lat, geo.lon)
} else {
    cost = shipping(fromMunicipality: a.ibge)
}
```

### Many CEPs at once

Do not loop over `lookup`. Use `lookupMany`, which resolves up to 500 CEPs per
request:

```swift
let ceps = ["01001000", "99999999", "20040020"]
let result = try await Client.shared.lookupMany(ceps)

for (requested, address) in zip(ceps, result) {
    if let address {
        print("\(requested): \(address.localidade)")
    } else {
        print("\(requested): not found")
    }
}
```

The returned array 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 throw.

Arrays 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 == nil`,
> 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:

```swift
let h = try await Client.shared.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 is an
immutable value and safe to share across tasks and threads:

```swift
let client = Client(
    baseURL: URL(string: "https://cep.is")!,  // point at another instance
    timeout: 10,        // seconds per request
    maxAttempts: 3,     // counting the first; 1 disables retrying
    backoffBase: 0.5,   // base of the exponential wait
    backoffMax: 8,      // cap on each wait, Retry-After included
    totalTimeout: nil   // cap on the whole call, attempts included
)

let address = try await client.lookup("01001000")
```

`timeout` is `URLRequest.timeoutInterval`, which measures inactivity rather
than total elapsed time; `totalTimeout` is the hard cap on the whole call.

Retries cover 429, 5xx and network failures, with exponential backoff and
jitter; 400 and 404 are never retried.

`Client.shared` is a ready-made instance with the defaults.

### 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`:

```swift
let client = Client(baseURL: URL(string: "http://localhost:8080")!)
```

## Errors

Everything throws `CepisError`. Its cases split by **the decision you have to
make**, not by the HTTP status that caused them:

| case | when | does retrying help? |
| --- | --- | --- |
| `invalidCEP` | not 8 digits | no |
| `cepNotFound` | well-formed, not in the database | no |
| `rateLimited` | 429; carries `retryAfter` | yes, later |
| `serverError` | 5xx; carries `status` | yes, later |
| `networkError` | DNS, connection, timeout, TLS | yes, later |
| `invalidResponse` | unintelligible response | probably not |

```swift
do {
    let address = try await Client.shared.lookup(cepFromForm)
} catch CepisError.cepNotFound {
    // ask the user for another CEP
} catch let error as CepisError {
    // network, server, rate limit: reschedule
    print(error.message, error.isRetriable)
}
```

`invalidResponse` 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

```sh
make           # list the targets
make test      # run the suite
make lint      # swift-format lint, touches nothing
make build     # compile the library
make check     # lint, then test, then build
```

`lint` and `format` need `swift format` (Swift 6 toolchains) or `swift-format`
on `PATH`; they report and skip when it is missing.

## Licence

ISC. See [LICENSE](LICENSE).