# 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

```bash
npm install @unicep/core
```

```bash
pnpm add @unicep/core
```

```bash
yarn add @unicep/core
```

```bash
bun add @unicep/core
```

## Your first lookup

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

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

[React](/en/docs/react)
  [Vue](/en/docs/vue)
  [Angular](/en/docs/angular)
  [Implement with AI](/en/docs/ai)
## Next steps

- [How it works](/en/docs/how-it-works): fallback, circuit breaker and errors.
- [Core](/en/docs/core): timeout, retry, cache and cancellation.
- [Providers](/en/docs/providers): configure, reorder or write your own.