Skip to content

Getting started

unicep queries several CEP services behind a single interface. If one service goes down, it moves on to the next one and always returns the same Address object. It works in the browser and on Node.js 20 or newer.

Janela do terminal
npm install @unicep/core
import { Unicep, defaultProviders } from '@unicep/core';
const unicep = new Unicep({ providers: defaultProviders() });
const address = await unicep.lookup('01310-100'); // with or without the hyphen
// {
// cep: '01310100',
// street: 'Avenida Paulista',
// complement: 'de 612 a 1510 - lado par',
// neighborhood: 'Bela Vista',
// city: 'São Paulo',
// state: 'SP',
// ibgeCode: '3550308',
// provider: 'viacep'
// }

The provider field tells you who answered. complement and ibgeCode may be missing, because not every service returns them. For CEPs that cover a whole city, street and neighborhood are empty.

The core is plain TypeScript. For React, Vue and Angular there are bindings that look up on their own once the CEP is valid.

  • How it works: fallback, circuit breaker and errors.
  • Core: timeout, retry, cache and cancellation.
  • Providers: configure, reorder or write your own.