BuscaCEP é uma biblioteca de consulta de endereço online, que permite consulta por CEP (Código de Endereçamento Postal) ou por logradouro (UF, Localidade e Logradouro).
Implementado na linguagem Delphi, utiliza o conceito de fluent interface para guiar no uso da biblioteca, desenvolvida para oferecer praticidade e eficiência, a BuscaCEP integra os principais players do mercado: Correios, ViaCEP, BrasilAPI, entre outros.
- Consulta Abrangente: BuscaCEP permite consultar tanto por CEP quanto por logradouro, flexibilizando a obtenção das informações de endereço.
- Consulta Detalhada: Com BuscaCEP as informações do endereço são completas, incluindo: logradouro, complemento, bairro, CEP, localidade, estado, região e código IBGE.
- Código IBGE: Com BuscaCEP o código IBGE é fornecido de forma off-line através do arquivo IBGE.dat disponibilizado junto com a biblioteca.
- Integração com Principais Players: Integrado com os principais serviços de consulta de CEP do Brasil: Correios, ViaCEP, BrasilAPI, entre outros.
- Facilidade de Integração: Com uma interface amigável e documentação detalhada, a BuscaCEP é fácil de integrar em qualquer projeto.
- Exemplos de uso: Repositório com diversos exemplos de uso da biblioteca, por exemplo, VCL, FMX e um servidor de aplicação em (Horse) simulando uma API de endereços.
Utilizando o Boss (Dependency manager for Delphi) é possível instalar a biblioteca de forma automatizada.
boss install https://github.com/antoniojmsjr/BuscaCEP
Se você optar por instalar manualmente, basta adicionar as seguintes pastas ao seu projeto, em Project > Options > Delphi Compiler > Target > All Configurations > Search path
..\BuscaCEP\Source
Provedor | Usa APIKey? | Busca por CEP? | * Busca por Logradouro? | ** Usa IBGE.dat? |
---|---|---|---|---|
Correios | NÃO | SIM | SIM | SIM |
Via CEP | NÃO | SIM | SIM | NÃO |
Brasil API | NÃO | SIM | NÃO | SIM |
CEP Aberto | SIM | SIM | SIM | NÃO |
Republica Virtual | NÃO | SIM | NÃO | SIM |
CEP Certo | NÃO | SIM | SIM | SIM |
KingHost | SIM | SIM | NÃO | SIM |
Postmon | NÃO | SIM | NÃO | NÃO |
CEP Livre | SIM | SIM | SIM | SIM |
Open CEP | SIM | SIM | SIM | NÃO |
API CEP | SIM | SIM | SIM | SIM |
Brasil Aberto | SIM | SIM | SIM | SIM |
* Para consultar usando o logradouro são necessários três parâmetros obrigatórios (UF, Cidade e Logradouro).
** Algumas APIs de CEP não retornam o código IBGE na consulta. Por isso, é utilizado o arquivo IBGE.dat para fornecer esse código.
Para disponibilizar o código IBGE da localidade no retorno da consulta, foi criado o arquivo IBGE.dat com base na API de localidades do IBGE.
- O arquivo dever ser usado junto ao aplicativo ou ser definido na biblioteca.
- Esse arquivo pode ser atualizado usando o projeto BuscaCEPIBGE.
Os exemplos estão disponíveis na pasta do projeto:
..\BuscaCEP\Samples
Consulta por CEP
uses
BuscaCEP, BuscaCEP.Types, BuscaCEP.Interfaces, System.SysUtils;
var
lBuscaCEPResponse: IBuscaCEPResponse;
lMsgError: string;
begin
try
lBuscaCEPResponse := TBuscaCEP.New
//.SetArquivoIBGE() [OPCIONAL]
.Providers[TBuscaCEPProvidersKind.Correios]
//.SetAPIKey() [CONFORME O PROVEDOR]
.Filtro
.SetCEP('90520-003')
.Request
//.SetTimeout() [OPCIONAL]
.Execute;
except
on E: EBuscaCEPRequest do
begin
lMsgError := Concat(lMsgError, Format('Provider: %s', [E.Provider]), sLineBreak);
lMsgError := Concat(lMsgError, Format('DateTime: %s', [DateTimeTostr(E.DateTime)]), sLineBreak);
lMsgError := Concat(lMsgError, Format('Kind: %s', [E.Kind.AsString]), sLineBreak);
lMsgError := Concat(lMsgError, Format('URL: %s', [E.URL]), sLineBreak);
lMsgError := Concat(lMsgError, Format('Method: %s', [E.Method]), sLineBreak);
lMsgError := Concat(lMsgError, Format('Status Code: %d', [E.StatusCode]), sLineBreak);
lMsgError := Concat(lMsgError, Format('Status Text: %s', [E.StatusText]), sLineBreak);
lMsgError := Concat(lMsgError, Format('Message: %s', [E.Message]));
Application.MessageBox(PWideChar(lMsgError), 'A T E N Ç Ã O', MB_OK + MB_ICONERROR);
Exit;
end;
on E: Exception do
begin
Application.MessageBox(PWideChar(E.Message), 'A T E N Ç Ã O', MB_OK + MB_ICONERROR);
Exit;
end;
end;
end;
Consulta por Logradouro
uses
BuscaCEP, BuscaCEP.Types, BuscaCEP.Interfaces, System.SysUtils;
var
lBuscaCEPResponse: IBuscaCEPResponse;
lMsgError: string;
begin
try
lBuscaCEPResponse := TBuscaCEP.New
//.SetArquivoIBGE() [OPCIONAL]
.Providers[TBuscaCEPProvidersKind.Correios]
//.SetAPIKey() [CONFORME O PROVEDOR]
.Filtro
.SetLogradouro('Avenida Plínio Brasil Milano')
.SetLocalidade('Porto Alegre')
.SetUF('RS')
.&End
.Request
//.SetTimeout() [OPCIONAL]
.Execute;
except
on E: EBuscaCEPRequest do
begin
lMsgError := Concat(lMsgError, Format('Provider: %s', [E.Provider]), sLineBreak);
lMsgError := Concat(lMsgError, Format('DateTime: %s', [DateTimeTostr(E.DateTime)]), sLineBreak);
lMsgError := Concat(lMsgError, Format('Kind: %s', [E.Kind.AsString]), sLineBreak);
lMsgError := Concat(lMsgError, Format('URL: %s', [E.URL]), sLineBreak);
lMsgError := Concat(lMsgError, Format('Method: %s', [E.Method]), sLineBreak);
lMsgError := Concat(lMsgError, Format('Status Code: %d', [E.StatusCode]), sLineBreak);
lMsgError := Concat(lMsgError, Format('Status Text: %s', [E.StatusText]), sLineBreak);
lMsgError := Concat(lMsgError, Format('Message: %s', [E.Message]));
Application.MessageBox(PWideChar(lMsgError), 'A T E N Ç Ã O', MB_OK + MB_ICONERROR);
Exit;
end;
on E: Exception do
begin
Application.MessageBox(PWideChar(E.Message), 'A T E N Ç Ã O', MB_OK + MB_ICONERROR);
Exit;
end;
end;
end;
Resultado da Consulta [IBuscaCEPResponse]
uses
BuscaCEP.Types, BuscaCEP.Interfaces;
var
lBuscaCEPResponse: IBuscaCEPResponse;
lBuscaCEPLogradouro: TBuscaCEPLogradouro;
begin
for lBuscaCEPLogradouro in lBuscaCEPResponse.Logradouros do
begin
lBuscaCEPLogradouro.Logradouro;
lBuscaCEPLogradouro.Complemento;
lBuscaCEPLogradouro.Unidade;
lBuscaCEPLogradouro.Bairro;
lBuscaCEPLogradouro.Localidade.Nome;
lBuscaCEPLogradouro.Localidade.IBGE;
lBuscaCEPLogradouro.Localidade.Estado.Nome;
lBuscaCEPLogradouro.Localidade.Estado.IBGE;
lBuscaCEPLogradouro.Localidade.Estado.Sigla;
lBuscaCEPLogradouro.Localidade.Estado.Regiao.Nome;
lBuscaCEPLogradouro.Localidade.Estado.Regiao.IBGE;
lBuscaCEPLogradouro.Localidade.Estado.Regiao.Sigla;
lBuscaCEPLogradouro.CEP;
end;
Resultado da Consulta [JSON]
{
"provider": "#CORREIOS",
"date_time": "2024-05-01T02:35:14.772-03:00",
"request_time": "75ms",
"total": 1,
"logradouros": [
{
"logradouro": "Avenida Plínio Brasil Milano",
"complemento": "de 1947 ao fim - lado ímpar",
"unidade": "",
"bairro": "Passo da Areia",
"cep": "90520003",
"localidade": {
"ibge": 4314902,
"nome": "Porto Alegre",
"estado": {
"ibge": 43,
"nome": "Rio Grande do Sul",
"sigla": "RS",
"regiao": {
"ibge": 4,
"nome": "Sul",
"sigla": "S"
}
}
}
}
]
}
- VCL
- VCL Client
- VCL Server (Horse)
Download: Demos.zip
BuscaCEP.mp4
ServidorAplicacao.mp4
BuscaCEP
is free and open-source software licensed under the