Release Stars Forks Issues

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

:beginner: Provedores Homologados

| Provedor | Usa APIKey? | Busca por CEP? | * Busca por Logradouro? | TBuscaCEPProvidersKind | |---|---|---|---|---| | Correios | NÃO | SIM | SIM | Correios | | Via CEP | NÃO | SIM | SIM | ViaCEP | | Brasil API | NÃO | SIM | NÃO | BrasilAPI | | CEP Aberto | SIM | SIM | SIM | CEPAberto | | Republica Virtual | NÃO | SIM | NÃO | RepublicaVirtual | | CEP Certo | NÃO | SIM | SIM | CEPCerto | | KingHost | SIM | SIM | NÃO | KingHost | KingHost | | Postmon | NÃO | SIM | NÃO | Postmon | | CEP Livre | SIM | SIM | SIM | CEPLivre | | Open CEP | SIM | SIM | SIM | OpenCEP | | API CEP | SIM | SIM | SIM | ApiCEP | | Brasil Aberto | SIM | SIM | SIM | BrasilAberto | | AwesomeAPI | NÃO | SIM | NÃO | AwesomeAPI |

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

:globe_with_meridians: 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":

BuscaCEP

Install / Use

README

BuscaCEP

Recursos:

⚙️ Instalação Automatizada

⚙️ Instalação Manual

:beginner: Provedores Homologados

:globe_with_meridians: Arquivo de Cache(BuscaCEP.dat)

⚡️ Uso da biblioteca