Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/BrasilAPI/cep-promise
Busca por CEP integrado diretamente aos serviços dos Correios, ViaCEP e outros (Node.js e Browser)
https://github.com/BrasilAPI/cep-promise
browser cep cep-promise correios hacktoberfest javascript nodejs promise-support viacep zipcode
Last synced: 16 days ago
JSON representation
Busca por CEP integrado diretamente aos serviços dos Correios, ViaCEP e outros (Node.js e Browser)
- Host: GitHub
- URL: https://github.com/BrasilAPI/cep-promise
- Owner: BrasilAPI
- License: mit
- Created: 2015-11-30T12:27:16.000Z (almost 9 years ago)
- Default Branch: master
- Last Pushed: 2024-03-28T22:32:41.000Z (8 months ago)
- Last Synced: 2024-05-16T05:46:11.573Z (6 months ago)
- Topics: browser, cep, cep-promise, correios, hacktoberfest, javascript, nodejs, promise-support, viacep, zipcode
- Language: JavaScript
- Homepage:
- Size: 708 KB
- Stars: 2,849
- Watchers: 82
- Forks: 320
- Open Issues: 37
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
CEP Promise
Busca por CEP integrado diretamente aos serviços dos Correios, ViaCEP e WideNet (Node.js e Browser)
## Features
* Sempre atualizado em tempo-real por se conectar diretamente aos serviços dos Correios, ViaCEP e WideNet.
* Possui alta disponibilidade por usar vários serviços como fallback.
* Sempre retorna a resposta mais rápida por fazer as consultas de forma concorrente.
* Sem limites de uso (rate limits) conhecidos.
* Interface de Promise extremamente simples.
* Suporte ao Node.js `10.x`, `11.x`, `12.x`, `13.x`, `14.x` e `@stable`.
* Suporte ao Node.js `4.x`, `5.x`, `6.x`, `7.x`, `8.x`, `9.x`, até cep-promise versão `3.0.9`.
* Suporte ao Node.js `0.10.x` e `0.12.x` até cep-promise versão `2.0.8`.
* 100% de code coverage com testes unitários e E2E.
* Desenvolvido utilizando ES6.
## Como utilizar
Teste e aprenda aqui.
### Realizando uma consulta
Por ser multifornecedor, a biblioteca irá resolver a Promise com o fornecedor que **mais rápido** lhe responder.
``` js
import cep from 'cep-promise'
cep('05010000')
.then(console.log)
// {
// "cep": "05010000",
// "state": "SP",
// "city": "São Paulo",
// "street": "Rua Caiubí",
// "neighborhood": "Perdizes",
// }
```
### Você também poderá passar o CEP como Inteiro
Em muitos sistemas o CEP é utilizado erroneamente como um Inteiro (e com isto cortando todos os zeros à esquerda). Caso este seja o seu caso, não há problema, pois a biblioteca irá preencher os caracteres faltantes na String, por exemplo:
``` js
import cep from 'cep-promise'
// enviando sem ter um zero à esquerda do CEP "05010000"
cep(5010000)
.then(console.log)
// {
// "cep": "05010000",
// "state": "SP",
// "city": "São Paulo",
// "street": "Rua Caiubí",
// "neighborhood": "Perdizes",
// }
```
### Quando o CEP não é encontrado
Neste caso será retornado um `"service_error"` e por ser multifornecedor, a biblioteca irá rejeitar a Promise apenas quando tiver a resposta negativa de todos os fornecedores.
``` js
import cep from 'cep-promise'
cep('99999999')
.catch(console.log)
// {
// name: 'CepPromiseError',
// message: 'Todos os serviços de CEP retornaram erro.',
// type: 'service_error',
// errors: [{
// message: 'CEP NAO ENCONTRADO',
// service: 'correios'
// }, {
// message: 'CEP não encontrado na base do ViaCEP.',
// service: 'viacep'
// }]
// }
```
### Quando o CEP possui um formato inválido
Neste caso será retornado um `"validation_error"` e a biblioteca irá rejeitar imediatamente a Promise, sem chegar a consultar nenhum fornecedor.
``` js
import cep from 'cep-promise'
cep('123456789123456789')
.catch(console.log)
// {
// name: 'CepPromiseError',
// message: 'CEP deve conter exatamente 8 caracteres.',
// type: 'validation_error',
// errors: [{
// message: 'CEP informado possui mais do que 8 caracteres.',
// service: 'cep_validation'
// }]
// }
```
### Options
- `timeout`: Timeout em milisegundos das consultas em cada serviço. O tempo total poderá ser maior devido a limites no paralelismo.
- `providers`: Lista de providers a serem usados na consulta. Default é usar todos os providers disponíveis.
```js
import cep from 'cep-promise'
cep('5010000', { timeout: 5000, providers: ['brasilapi'] })
.then(console.log)
```
### Instalação
#### Browser usando CDN
```
```
#### npm
```
$ npm install --save cep-promise
```
#### Bower
```
$ bower install --save cep-promise
```
#### yarn
```
$ yarn add cep-promise
```
#### Angular 2
``` ts
import * as cep from 'cep-promise'
cep('05010000')
.then(console.log)
```
## Como contribuir
Leia nosso guia de contribuição [aqui](CONTRIBUTING.md)
## Contribuidores
## Autor
| [
@filipedeschamps](https://github.com/filipedeschamps) |
| :---: |