Orientação gerada a partir de informações públicas. Apenas para referência.
O pacote search_cep simplifica a comunicação com a API via_cep para obter rapidamente informações detalhadas sobre códigos postais brasileiros (CEPs) e seus respectivos locais. Ele fornece uma interface fácil de usar para buscar dados como rua, bairro, cidade e estado, tornando-se ideal para aplicações que exigem geolocalização ou validação de endereços no Brasil. O pacote suporta múltiplas plataformas, incluindo Android, iOS, Web, macOS, Windows e Linux, garantindo ampla compatibilidade em projetos Flutter.
Casos de uso
Pesquisa de endereço por CEP
integração de geolocalização brasileira
Validação de formulário com dados de CEP
Preenchimento automático de endereço
Recuperação de dados de localização em tempo real
Principais recursos
Integração simples da API
Suporta todas as principais plataformas
Tempos de resposta rápidos
Detalhes abrangentes do CEP
Tratamento de erros para CEPs inválidos
Indicado para
Aplicativos Flutter direcionados ao Brasil
Aplicativos que precisam de autocomplete de endereço
Serviços baseados em localização
Plataformas de comércio eletrônico
sistemas governamentais ou logísticos
Considerações
Requer conexão com a internet
Depende da API externa via_cep
Limites de taxa podem ser aplicados
A precisão dos dados depende da fonte de terceiros
Nenhuma cache offline incluída
README original
Snapshot do README original do repositório-fonte vinculado. Consulte o repositório para o conteúdo mais recente.
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.
