BuscaCEP

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.

Recursos:

• 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.

⚙️ Instalação Automatizada

Utilizando o Boss (Dependency manager for Delphi) é possível instalar a biblioteca de forma automatizada.

boss install https://github.com/antoniojmsjr/BuscaCEP

⚙️ Instalação Manual

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

🔰 Provedores Homologados

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, então é utilizado o arquivo IBGE.dat para disponibilizar esse código.

🌐 Código IBGE

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.

⚡️ Uso da biblioteca

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"
          }
        }
      }
    }
  ]
}

Exemplo compilado

• VCL
• VCL Client
• VCL Server (Horse)

Download: Demo.zip

BuscaCEP.mp4

ServidorAplicacao.mp4

⚠️ Licença

BuscaCEP is free and open-source software licensed under the