{"id":13403752,"url":"https://github.com/BrasilAPI/cep-promise","last_synced_at":"2025-03-14T08:32:13.501Z","repository":{"id":37465095,"uuid":"47116945","full_name":"BrasilAPI/cep-promise","owner":"BrasilAPI","description":"Busca por CEP integrado diretamente aos serviços dos Correios, ViaCEP e outros (Node.js e Browser)","archived":false,"fork":false,"pushed_at":"2024-03-28T22:32:41.000Z","size":725,"stargazers_count":2849,"open_issues_count":37,"forks_count":320,"subscribers_count":82,"default_branch":"master","last_synced_at":"2024-05-16T05:46:11.573Z","etag":null,"topics":["browser","cep","cep-promise","correios","hacktoberfest","javascript","nodejs","promise-support","viacep","zipcode"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BrasilAPI.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-11-30T12:27:16.000Z","updated_at":"2024-06-12T05:57:40.794Z","dependencies_parsed_at":"2023-02-05T01:30:22.475Z","dependency_job_id":"9851f686-7101-481b-a460-98a8bb321634","html_url":"https://github.com/BrasilAPI/cep-promise","commit_stats":{"total_commits":245,"total_committers":43,"mean_commits":"5.6976744186046515","dds":0.5918367346938775,"last_synced_commit":"887608fcdb9e0546fb4f7f05a00a54e4f05b772a"},"previous_names":[],"tags_count":33,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BrasilAPI%2Fcep-promise","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BrasilAPI%2Fcep-promise/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BrasilAPI%2Fcep-promise/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BrasilAPI%2Fcep-promise/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BrasilAPI","download_url":"https://codeload.github.com/BrasilAPI/cep-promise/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221449556,"owners_count":16823612,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["browser","cep","cep-promise","correios","hacktoberfest","javascript","nodejs","promise-support","viacep","zipcode"],"created_at":"2024-07-30T19:01:34.091Z","updated_at":"2024-10-25T18:32:32.772Z","avatar_url":"https://github.com/BrasilAPI.png","language":"JavaScript","readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"http://piskel-imgstore-b.appspot.com/img/d580e96e-bd8a-11e6-b157-9949cad4d609.gif\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eCEP Promise\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://npm-stat.com/charts.html?package=cep-promise\"\u003e\n    \u003cimg src=\"https://img.shields.io/npm/dm/cep-promise.svg\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://coveralls.io/github/BrasilAPI/cep-promise?branch=master\"\u003e\n    \u003cimg src=\"https://coveralls.io/repos/github/BrasilAPI/cep-promise/badge.svg?branch=master\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/cep-promise\"\u003e\n    \u003cimg src=\"https://badge.fury.io/js/cep-promise.svg\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"http://standardjs.com/\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/code%20style-standard-brightgreen.svg\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://snyk.io/test/github/BrasilAPI/cep-promise\"\u003e\n    \u003cimg src=\"https://snyk.io/test/github/BrasilAPI/cep-promise/badge.svg\" alt=\"Known Vulnerabilities\" data-canonical-src=\"https://snyk.io/test/github/BrasilAPI/cep-promise\" style=\"max-width:100%;\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  Busca por CEP integrado diretamente aos serviços dos Correios, ViaCEP e WideNet (Node.js e Browser)\n\u003c/p\u003e\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 \u003ca href=\"https://npm.runkit.com/cep-promise\" target=\"_blank\"\u003eaqui\u003c/a\u003e.\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\u003cscript src=\"https://cdn.jsdelivr.net/npm/cep-promise/dist/cep-promise.min.js\"\u003e\u003c/script\u003e\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\u003ca href=\"https://github.com/brasilapi/cep-promise/graphs/contributors\"\u003e\u003cimg src=\"https://contrib.rocks/image?repo=brasilapi/cep-promise\" /\u003e\u003c/a\u003e\n\n## Autor\n\n| [\u003cimg src=\"https://avatars0.githubusercontent.com/u/4248081?v=3\u0026s=115\"\u003e\u003cbr\u003e\u003csub\u003e@filipedeschamps\u003c/sub\u003e](https://github.com/filipedeschamps) |\n| :---: |","funding_links":[],"categories":["JavaScript","hacktoberfest","nodejs"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FBrasilAPI%2Fcep-promise","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FBrasilAPI%2Fcep-promise","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FBrasilAPI%2Fcep-promise/lists"}