@br-geo-kit/provider-opencep

OpenCEP for br-geo-kit. Open, self-hostable, ViaCEP-shaped.

pnpm add @br-geo-kit/cep @br-geo-kit/provider-opencep

import { createCep } from '@br-geo-kit/cep'
import { opencep } from '@br-geo-kit/provider-opencep'

const cep = createCep({ providers: [opencep()] })

What it returns

| | | | --- | --- | | Street, neighbourhood, city, state | yes | | Correios side-of-street note | yes | | IBGE code | yes | | Area code | no — the kit fills it from the offline dataset | | Coordinates | no | | Reverse lookup | no |

Unlike ViaCEP it omits absent fields rather than sending "", and it answers a missing CEP with an honest 404.

Run your own

This is the reason to reach for it. The base is open and self-hostable, so a chain can lead with infrastructure you control:

createCep({
  providers: [
    opencep({ baseUrl: 'http://cep.internal:3000/v1' }),
    brasilapi(),
  ],
})

Your instance absorbs the traffic, a public service covers the gaps.

It shares a base with BrasilAPI

OpenCEP is the open-cep base that BrasilAPI falls through to. The two are therefore not independent sources: where they disagree with ViaCEP they tend to disagree together, and CEP 99999-999 — which does not exist but has a record in Sarandi/PR — is the standing example.

A consensus chain of [brasilapi(), opencep()] is weaker than it looks. Two of those agreeing is one opinion. Put ViaCEP in the chain if you want a second one.

Options

opencep({ baseUrl: 'https://opencep.com/v1' })

Rate limits

The public instance publishes no documented rate limit and no SLA. Cache, or host your own. See caching.

Licence

MIT.

This package is an API client and redistributes no data. It is not affiliated with, endorsed by, or sponsored by OpenCEP; the name identifies the service it connects to. OpenCEP has its own terms of use, and calling it is your relationship with them.