![](\"http://piskel-imgstore-b.appspot.com/img/d580e96e-bd8a-11e6-b157-9949cad4d609.gif\")
\n\n \n
\n \n ![](\"https://img.shields.io/npm/dm/cep-promise.svg\")
\n \n \n ![](\"https://coveralls.io/repos/github/BrasilAPI/cep-promise/badge.svg?branch=master\"){kind=icon}
\n \n \n ![](\"https://badge.fury.io/js/cep-promise.svg\"){kind=icon}
\n \n \n ![](\"https://img.shields.io/badge/code%20style-standard-brightgreen.svg\"){kind=icon}
\n \n \n ![\"Known](\"https://snyk.io/test/github/BrasilAPI/cep-promise/badge.svg\"){kind=icon}
\n \n
\n Busca por CEP integrado diretamente aos serviços dos Correios, ViaCEP e WideNet (Node.js e Browser)\n
\n\n## Features\n\n * Sempre atualizado em tempo-real por se conectar diretamente aos serviços dos Correios, ViaCEP e WideNet.\n * Possui alta disponibilidade por usar vários serviços como fallback.\n * Sempre retorna a resposta mais rápida por fazer as consultas de forma concorrente.\n * Sem limites de uso (rate limits) conhecidos.\n * Interface de Promise extremamente simples.\n * Suporte ao Node.js `10.x`, `11.x`, `12.x`, `13.x`, `14.x` e `@stable`.\n * Suporte ao Node.js `4.x`, `5.x`, `6.x`, `7.x`, `8.x`, `9.x`, até cep-promise versão `3.0.9`.\n * Suporte ao Node.js `0.10.x` e `0.12.x` até cep-promise versão `2.0.8`.\n * 100% de code coverage com testes unitários e E2E.\n * Desenvolvido utilizando ES6.\n\n\n## Como utilizar\n\nTeste e aprenda aqui.\n\n### Realizando uma consulta\n\nPor ser multifornecedor, a biblioteca irá resolver a Promise com o fornecedor que **mais rápido** lhe responder.\n\n``` js\nimport cep from 'cep-promise'\n\ncep('05010000')\n .then(console.log)\n\n // {\n // \"cep\": \"05010000\",\n // \"state\": \"SP\",\n // \"city\": \"São Paulo\",\n // \"street\": \"Rua Caiubí\",\n // \"neighborhood\": \"Perdizes\",\n // }\n```\n\n\n### Você também poderá passar o CEP como Inteiro\n\nEm 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:\n\n``` js\nimport cep from 'cep-promise'\n\n// enviando sem ter um zero à esquerda do CEP \"05010000\"\ncep(5010000)\n .then(console.log)\n\n // {\n // \"cep\": \"05010000\",\n // \"state\": \"SP\",\n // \"city\": \"São Paulo\",\n // \"street\": \"Rua Caiubí\",\n // \"neighborhood\": \"Perdizes\",\n // }\n```\n\n### Quando o CEP não é encontrado\n\nNeste 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.\n\n``` js\nimport cep from 'cep-promise'\n\ncep('99999999')\n .catch(console.log)\n\n // {\n // name: 'CepPromiseError',\n // message: 'Todos os serviços de CEP retornaram erro.',\n // type: 'service_error',\n // errors: [{\n // message: 'CEP NAO ENCONTRADO',\n // service: 'correios'\n // }, {\n // message: 'CEP não encontrado na base do ViaCEP.',\n // service: 'viacep'\n // }]\n // }\n\n```\n\n### Quando o CEP possui um formato inválido\n\nNeste caso será retornado um `\"validation_error\"` e a biblioteca irá rejeitar imediatamente a Promise, sem chegar a consultar nenhum fornecedor.\n\n``` js\nimport cep from 'cep-promise'\n\ncep('123456789123456789')\n .catch(console.log)\n\n // {\n // name: 'CepPromiseError',\n // message: 'CEP deve conter exatamente 8 caracteres.',\n // type: 'validation_error',\n // errors: [{\n // message: 'CEP informado possui mais do que 8 caracteres.',\n // service: 'cep_validation'\n // }]\n // }\n```\n### Options\n- `timeout`: Timeout em milisegundos das consultas em cada serviço. O tempo total poderá ser maior devido a limites no paralelismo.\n- `providers`: Lista de providers a serem usados na consulta. Default é usar todos os providers disponíveis.\n\n```js\nimport cep from 'cep-promise'\ncep('5010000', { timeout: 5000, providers: ['brasilapi'] })\n .then(console.log)\n\n```\n\n### Instalação\n\n#### Browser usando CDN\n```\n\n```\n\n#### npm\n\n```\n$ npm install --save cep-promise\n```\n\n#### Bower\n\n```\n$ bower install --save cep-promise\n```\n#### yarn\n\n```\n$ yarn add cep-promise\n```\n\n#### Angular 2\n\n``` ts\nimport * as cep from 'cep-promise'\n\ncep('05010000')\n .then(console.log)\n```\n\n## Como contribuir\n\nLeia nosso guia de contribuição [aqui](CONTRIBUTING.md)\n\n## Contribuidores\n\n![](\"https://avatars0.githubusercontent.com/u/4248081?v=3&s=115\")