BuscaCEP

BuscaCEP é uma biblioteca para consulta de endereços online, permitindo buscas 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.

Esta biblioteca é ideal para desenvolvedores Delphi que buscam uma solução robusta, flexível e eficiente para integrar consultas de endereços online em suas aplicações.

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, código IBGE e código DDD.
• 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?
Correios	NÃO	SIM	SIM
Via CEP	NÃO	SIM	SIM
Brasil API	NÃO	SIM	NÃO
CEP Aberto	SIM	SIM	SIM
Republica Virtual	NÃO	SIM	NÃO
CEP Certo	NÃO	SIM	SIM
KingHost	SIM	SIM	NÃO
Postmon	NÃO	SIM	NÃO
CEP Livre	SIM	SIM	SIM
Open CEP	SIM	SIM	SIM
API CEP	SIM	SIM	SIM
Brasil Aberto	SIM	SIM	SIM
AwesomeAPI	NÃO	SIM	NÃO

* Para consultar usando o logradouro, são necessários três parâmetros obrigatórios: UF, Cidade e Logradouro.

🌐 Arquivo de Cache(BuscaCEP.dat)

Para fornecer o código IBGE e o código DDD da localidade no retorno da consulta, foi criado o arquivo BuscaCEP.dat, com base na API de localidades do IBGE e nos dados disponibilizados pela Anatel.

• O arquivo deve ser usado juntamente com o aplicativo ou definido na biblioteca.
• Este arquivo pode ser atualizado utilizando o projeto BuscaCEPCache.

⚡️ 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
      //.SetArquivoCache() [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
      //.SetArquivoCache() [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.DDD;
    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,
        "ddd": 51,
        "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: Demos.zip

BuscaCEP.mp4

ServidorAplicacao.mp4

⚠️ Licença

BuscaCEP is free and open-source software licensed under the