Pacote criado para ser uma abstração e facilitar o uso da API via_cep ou da API Postmon. Ambas APIs fornecem pesquisa de localidade por CEP. Pelos testes que fiz a API do Postmon retorna dados mais atualizados,
já a API via_cep retorna dados mais completos. O pacote foi criado de maneira que o usuário tem a possibilidade de escolher
quais das duas opções de API achar melhor.
O pacote fornece uma classe para cada API com um métodos estático para fazer a busca de um CEP, onde o usuário manda uma String com o CEP e recebe várias informações daquele CEP.
A API via_cep fornece uma consulta adicional de pesquisa por localidades
onde o usuário passa uma UF, uma cidade e um logradouro e a API retorna uma lista de CEP's dentro daquela área. Neste último caso
o resultado será ordenado pela proximidade do nome do logradouro e possui limite máximo de 50 (cinquenta) CEPs.
Desta forma, quanto mais específico os parâmentros de entrada maior será a precisão do resultado.
💪 Totalmente testado
📝 Bem documentado
💼 Pronto para produção
⛏️Como Usar
via_cep
O exemplo básico de uso consiste em passar uma String sem formatação com o CEP e o pacote vai retornar um objeto
intitulado ViaCepInfo com as informações retornadas pela API.
voidmain() async {
final viaCepSearchCep = ViaCepSearchCep();
final infoCepJSON = await viaCepSearchCep.searchInfoByCep(cep: '01001000');
print(infoCepJSON);
}
O print do exemplo acima vai ser um objeto no formato indicado abaixo:
ViaCepInfo{cep: 01001-000, logradouro: Praça da Sé, complemento: lado ímpar, bairro: Sé, localidade: São Paulo, uf: SP, unidade: , ibge: 3550308, gia: 1004hasError: false}
Um exemplo que pode acontecer é o cep passado pelo usuário ser uma String válida mas pode ser que ele não exista, como
no exemplo abaixo:
voidmain() async {
final viaCepSearchCep = ViaCepSearchCep();
final infoCepJSON = await viaCepSearchCep.searchInfoByCep(cep: '99999999');
print(infoCepJSON);
}
Neste caso o objeto ViaCepInfo vai vir com todos os campos de valores nulos e um objeto [ViaCepSearchCepError] populado
indicando qual erro ocorreu e com um enum de tipo de erro ocorrido. Além disso o campo hasError do mesmo objeto virá com o
valor true, indicando que algum erro ocorreu.
ViaCepInfo{cep: null, logradouro: null, complemento: null, bairro: null, localidade: null, uf: null, unidade: null, ibge: null, gia: null, SearchCepError{errorMessage: CEP com formato válido, porém inexistente na base de dados, errorType: ErrorType.nonExistentCep} , hasError: true}
No caso da String com cep passada não ser válida o objeto ViaCepInfoCep retornado vai ser equivalente a esse:
O exemplo básico de uso consiste em passar uma String sem formatação com o CEP e o pacote vai retornar um objeto
intitulado PostmonCepInfo com as informações retornadas pela API.
voidmain() async {
final postmonSearchCep = PostmonSearchCep();
final infoCepJSON = await postmonSearchCep.searchInfoByCep(cep: '01001000');
print(infoCepJSON);
}
O print do exemplo acima vai ser um objeto no formato indicado abaixo:
PostmonCepInfo{bairro: Sé, cidade: São Paulo, logradouro: Praça da Sé, estadoInfo: EstadoInfo{areaKm2: 248.221,996, codigoIbge: 35, nome: São Paulo}, cep: 01001000, cidadeInfo: CidadeInfo{areaKm2: 1521,11, codigoIbge: 3550308}, estado: SP, hasError: false, postmonSearchCepError: null}
Um exemplo que pode acontecer é o cep passado pelo usuário ser uma String válida mas pode ser que ele não exista, como
no exemplo abaixo:
voidmain() async {
final postmonSearchCep = PostmonSearchCep();
final infoCepJSON = await postmonSearchCep.searchInfoByCep(cep: '99999999');
print(infoCepJSON);
}
Neste caso o objeto PostmonCepInfo vai vir com todos os campos de valores nulos e um objeto [PostmonSearchCepError] populado
indicando qual erro ocorreu Além disso o campo hasError do mesmo objeto virá com o valor true, indicando que algum erro ocorreu.
Para mais informações sobre a API e para ajudar a mantê-la atualizada via_cep.
API Postmon
Para mais informações sobre a API e para ajudar a mantê-la atualizada Postmon.
Breaking Changes
1.0.4 - 2.0.0: A versão 2.0.0 passa a separar os métodos para permitir compatibilidade com a API do Postmon. Ficando a cargo do usuário escolher qual API utilizar.
2.0.0 - 3.0.0: A versão 3 do pacote retira os métodos estáticos e os torna métodos de instâncias. Essa mudança visa tornar o código mais testável e mais estável.
Todo
[x] Criar testes
[x] Tornar o código mais testável
[x] Adicionar uma abordagem mais funcional com o dartz
Sugestões, Melhorias e Bugs
Para sugerir melhorias ou para apontar algum bug issue tracker.
