Skip to content

Latest commit

 

History

History
256 lines (220 loc) · 10.5 KB

README.md

File metadata and controls

256 lines (220 loc) · 10.5 KB

Maintained YES Memory Leak Verified YES Release Stars Forks Issues
Compatibility Delphi Supported Versions


IPGeolocation


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 License