@br-geo-kit/provider-viacep

ViaCEP for br-geo-kit. The only public service with a reverse lookup.

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

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

const cep = createCep({ providers: [viacep()] })
await cep.lookup('01310-100')

What it returns

| | | | --- | --- | | Street, neighbourhood, city, state | yes | | Correios side-of-street note (complemento) | yes — one of only two | | IBGE code | yes | | Area code | yes | | Coordinates | no | | Time zone | no | | Reverse lookup | yes — the only public service that has it |

The trap this adapter closes

ViaCEP answers a CEP that does not exist with HTTP 200 and a body of {"erro": "true"}. An integration that checks response.ok and parses the body into its form gets an object whose every field is undefined, and shows the user a blank form with no error.

Worse: when ViaCEP is rate-limiting it answers HTTP 200 with an HTML page. The same integration reads that as a successful lookup too.

This adapter reads the first as null — the CEP does not exist — and throws on the second, so the resolver falls through to the next provider instead of telling the user their address is invalid.

It also turns ViaCEP's empty strings back into null. ViaCEP writes "" and never null, and a CEP único covering a whole small municipality legitimately has no street. "" and "the source is silent" are different facts.

Reverse lookup

await cep.reverse({ state: 'SP', city: 'São Paulo', street: 'Paulista' })

ViaCEP requires at least three characters in the city and the street and answers 400 otherwise; the adapter returns [] for a shorter query rather than letting a predictable 400 abort the chain. A search with no match answers []; a malformed one answers {"erro": "true"}, which is not an array, and is also read as no match.

Options

viacep({ baseUrl: 'https://my-proxy.example/ws' })

Rate limits

ViaCEP publishes no documented rate limit and no SLA. Use a cache, and put a second provider behind it. See caching and providers.

Licence

MIT.

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