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.
Installation
Section titled “Installation”npm install @unicep/corepnpm add @unicep/coreyarn add @unicep/corebun add @unicep/coreYour first lookup
Section titled “Your first lookup”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.
With your framework
Section titled “With your framework”The core is plain TypeScript. For React, Vue and Angular there are bindings that look up on their own once the CEP is valid.
ReactThe useCep hook
VueThe useCep composable
AngularinjectCep with signals and RxJS
Implement with AIReady-made prompts and llms.txt
Next steps
Section titled “Next steps”- How it works: fallback, circuit breaker and errors.
- Core: timeout, retry, cache and cancellation.
- Providers: configure, reorder or write your own.