Package selection guidance compiled from public package information, community data, and project usage.
The search_cep package simplifies communication with the via_cep API to quickly retrieve detailed information about Brazilian postal codes (CEPs) and their corresponding locations. It provides an easy-to-use interface for fetching data such as street, neighborhood, city, and state, making it ideal for applications requiring geolocation or address validation in Brazil. The package supports multiple platforms including Android, iOS, Web, macOS, Windows, and Linux, ensuring broad compatibility across Flutter projects.
Use cases
Address lookup by CEP
Brazilian geolocation integration
Form validation with CEP data
Automated address filling
Real-time location data retrieval
Key features
Simple API integration
Supports all major platforms
Fast response times
Comprehensive CEP details
Error handling for invalid CEPs
Suitable for
Flutter apps targeting Brazil
Apps needing address autocomplete
Location-based services
E-commerce platforms
Government or logistics systems
Considerations
Requires internet connection
Depends on external via_cep API
Rate limits may apply
Data accuracy relies on third-party source
No offline caching included
Original README
Original README snapshot from the linked source repository. Visit the repository for the latest content.
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.
