path: root/README.md

# cepis

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

```cpp
#include <cepis/cepis.hpp>
#include <iostream>

int main() {
  const cepis::Address a = cepis::lookup("01001-000");
  std::cout << a.logradouro << ' ' << a.localidade << ' ' << a.uf << '\n';
  // Praça da Sé São Paulo SP
}
```

Requires C++17 and libcurl. libcurl is the one dependency because the C++
standard library has no HTTP client and libcurl is already present on
essentially every system this will run on, TLS and certificate store included;
JSON and CSV are parsed in-tree, since the payloads are flat and a
general-purpose parser would be the larger dependency of the two.

## Installation

```sh
git clone https://git.cep.is/cpp.git cepis-cpp
cd cepis-cpp
make build            # build/libcepis.a and build/cepis-lookup
```

With CMake, either add the directory to your project or install it:

```cmake
add_subdirectory(cepis-cpp)
target_link_libraries(your_target PRIVATE cepis::cepis)
```

```sh
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build
cmake --install build --prefix /usr/local
```

Link manually with `-lcepis -lcurl`.

## Usage

### A single lookup

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

```cpp
const cepis::Address 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)
a.formatted_cep();  // "01310-100"
```

Fields the database does not have for that CEP come back as empty strings,
never absent. `a.raw` keeps the response as it arrived, so a field the API
grows before this library is updated is still reachable.

### Coordinates

About 57% of CEPs have a coordinate. When they do not, `geo` is empty:

```cpp
if (a.geo) {
  a.geo->lat;       // -23.567202
  a.geo->lon;       // -46.649659
  a.geo->raio_m;    // 1084
  a.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 |

`a.geo->is_precise()` is the shorthand for `precisao == "logradouro"`:

```cpp
const double cost = a.geo && a.geo->is_precise()
                        ? shipping_from(a.geo->lat, a.geo->lon)
                        : shipping_from_municipality(a.ibge);
```

### Many CEPs at once

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

```cpp
const std::vector<std::string> ceps = {"01001000", "99999999", "20040020"};
const std::vector<std::optional<cepis::Address>> result = cepis::lookup_many(ceps);

for (std::size_t i = 0; i < ceps.size(); ++i) {
  if (result[i]) {
    std::cout << ceps[i] << ": " << result[i]->localidade << '\n';
  } else {
    std::cout << ceps[i] << ": not found\n";
  }
}
```

The returned vector has **the same size and the same order** as the input. A
CEP that does not exist, or is malformed, is empty at its position — it does
not vanish, and it does not throw.

Inputs 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 an empty
> `geo`, 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:

```cpp
const cepis::Health h = cepis::health();

h.ok();             // 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 does not throw — that arrives in `h.status`.

## Configuration

For anything beyond the defaults, build a `Client` and reuse it. Its
configuration is fixed at construction and it keeps no state between calls, so
a `const Client&` is safe to share across threads:

```cpp
cepis::Config config;
config.base_url = "https://cep.is";                       // another instance
config.timeout = std::chrono::seconds{10};                // cap on one attempt
config.max_attempts = 3;                                  // 1 disables retrying
config.backoff_base = std::chrono::milliseconds{500};     // exponential base
config.backoff_max = std::chrono::seconds{8};             // cap on each wait
config.total_timeout = std::chrono::seconds{15};          // cap on the whole call

const cepis::Client client(config);
const cepis::Address a = client.lookup("01001000");
```

`timeout` caps one attempt — connection plus transfer — not each socket
operation, because that is how libcurl works. `total_timeout` is the cap on
the whole call, retries and waits included.

Retries cover 429, 5xx and network failures, with exponential backoff and
jitter; 400 and 404 are never retried. Each field is documented in
`include/cepis/client.hpp`.

The free functions (`cepis::lookup`, etc.) share one process-wide client. 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`:

```cpp
cepis::Config config;
config.base_url = "http://localhost:8080";
```

From the command line, to confirm quickly that it answers:

```sh
build/cepis-lookup --base-url http://localhost:8080 01001000
```

## Errors

Everything derives from `cepis::Error`, which derives from
`std::runtime_error`. 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? |
| --- | --- | --- |
| `InvalidCep` | not 8 digits | no |
| `CepNotFound` | well-formed, not in the database; may expose `faixa()` | no |
| `RateLimited` | 429; exposes `retry_after()` | yes, later |
| `ServerError` | 5xx; exposes `status()` | yes, later |
| `NetworkError` | DNS, connection, timeout, TLS | yes, later |
| `InvalidResponse` | unintelligible response | probably not |

```cpp
try {
  const cepis::Address a = cepis::lookup(cep_from_form);
} catch (const cepis::CepNotFound&) {
  // ask the user for another CEP
} catch (const cepis::Error&) {
  // transient failure: reschedule
}
```

### A CEP that does not exist

`CepNotFound` often knows **where the CEP would have been**. A CEP that fails
is rarely random: it is usually someone who knows the city and guessed the
number, and the classic guess is the `-000` that 957 municipalities never
received.

```cpp
try {
  const cepis::Address a = cepis::lookup("25845-000");
} catch (const cepis::CepNotFound& error) {
  if (error.faixa()) {
    error.faixa()->localidade;  // "Areal"
    error.faixa()->uf;          // "RJ"
    error.faixa()->ibge;        // "3300225"
    error.faixa()->cep_ini;     // "25845001"
    error.faixa()->cep_fim;     // "25849899"
    error.faixa()->ceps;        // 118
  }
}
```

Three things to keep straight:

- **It is still a 404.** `faixa` is context for an error, not an address. The
  CEP does not exist; nothing here makes it deliverable.
- **`cep_ini` and `cep_fim` are the CEPs that actually exist**, not the bounds
  the Correios publish. The DNE's own start for Areal is `25845000` — exactly
  the CEP that just failed.
- **The range is sparse.** Areal's 118 CEPs are scattered across the ~4,900
  numbers between `25845001` and `25849899`. That is what `ceps` is for; never
  present the pair as a list of valid CEPs.

When the CEP falls in a band no municipality owns, the API **omits** `faixa`
entirely — it never sends null — and `error.faixa()` is empty. A block that
cannot be read is empty too: a 404 is already the answer, and failing to read
the hint attached to it never turns into a parse error.

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

`Client`'s constructor throws `std::invalid_argument` for a configuration that
cannot work, such as `max_attempts = 0`.

## Development

Everything runs through `make`:

```sh
make            # list the targets
make test       # build and run the suite
make lint       # clang-format --dry-run + clang-tidy, touches nothing
make format     # apply clang-format
make build      # libcepis.a and the example CLI into build/
make check      # lint, then test, then build
```

The suite stands up a real HTTP server on a loopback port and points
`base_url` at it, so no test touches the network. Override the toolchain with
e.g. `make test CXX=clang++ STD=c++20`.

## Licence

ISC. See [LICENSE](LICENSE).