search_cep 패키지는 브라질 우편번호(CEP) 및 해당 위치에 대한 상세 정보를 신속하게 검색하기 위해 via_cep API와의 통신을 간소화합니다. 도로, 동네, 도시, 주 등의 데이터를 가져오는 사용하기 쉬운 인터페이스를 제공하여 브라질에서 지리적 위치 또는 주소 검증이 필요한 애플리케이션에 적합합니다. 이 패키지는 Android, iOS, Web, macOS, Windows, Linux 등 여러 플랫폼을 지원하며 Flutter 프로젝트에서 광범위한 호환성을 보장합니다.
사용 사례
우편번호로 주소 검색
브라질 위치 정보 통합
CEP 데이터를 사용한 폼 검증
주소 자동 채우기
실시간 위치 데이터 검색
주요 기능
간단한 API 통합
모든 주요 플랫폼을 지원합니다
빠른 응답 시간
포괄적인 CEP 세부 정보
유효하지 않은 CEP에 대한 오류 처리
적합한 대상
브라질을 대상으로 한 플러터 앱
주소 자동 완성 기능이 필요한 앱
위치 기반 서비스
전자상거래 플랫폼
정부 또는 물류 시스템
고려 사항
인터넷 연결이 필요합니다
외부 via_cep API에 의존합니다
레이트 제한이 적용될 수 있습니다
데이터 정확성은 제3자 소스에 의존합니다
오프라인 캐싱 포함되지 않음
원본 README
연결된 소스 저장소의 README 원문 스냅샷입니다. 최신 내용은 저장소에서 확인하세요.
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.
