Brasap - Consulta Cep Gratuíta

Consulte seu CEP:

AQUI VAI A RESPOSTA DA API

Conheça Mais Sobre Nossa API

Se você precisa implementar a busca de cep em seus aplicativos, você pode utilizar nossa API de maneira rápida e simples, basta implementar uma requisição para https://consultacep.brasap.com.br/api/cep/01031-970 utilizando o cep que deseja consultar, como no exemplo 01031-970 é o cep da Agencia Central dos Correios no - Vale do Anhangabau.
É muito simples, o retorno ocorre em formato JSON e pode ser usado em milhares de sistemas diferentes. Veja o exemplo do retorno para o cep 01031-970:
{
    "server": "BRASAP TECNOLOGIA E SISTEMAS LTDA - Versão 1.0",
    "exec_time": "0.123 - Segundos",
    "erro": false,
    "erro_no": "200",
    "erro_msg": "SUCESSO",
    "response": {
        "registros": "1",
        "dados": {
            "data_atualizacao": "15-04-2022 13:06:52",
            "cep": "01031970",
            "tipo": "AGENCIAS CORREIOS",
            "logradouro_completo": "Praça do Correio, s/n",
            "logradouro": "Praça do Correio, s/n",
            "complemento": "",
            "unidade": "Praça do Correio, s/n",
            "bairro": "Centro",
            "cidade": "São Paulo",
            "uf": "SP",
            "pais": "Brasil"
        }
    }
}
Esta é a resposta padrão, e é composta de um objeto JSON (JavaScript Object Notation), que é uma forma leve e baseada em texto legível por humanos para a troca de informações entre diferentes sistemas e programas, sendo a forma mais utilizada para a troce de informações entre APIs (Application Program Interface / Interface de Programação de Aplicação) no padrão REST.
O JSON é construído em uma coleção de pares nome/valor, que pode ser implementado em várias linguagens, onde cada um dos pares tem o significado abaixo:
  • server: Identificação do servidor e versão da api utilizada
  • exec_time: Tempo de resposta da API em milissegundos
  • erro: Um booleano que indica se houve erros da API, caso o valor retornado seja TRUE (verdadeiro), a API esta passando por dificuldades técnicas ou existiu algum erro no processamento, o erro retornado segue o código de retorno HTTP de estado.
  • erro_no: O núme do erro, seguindo o padrão HTTP caso queira utilizar mensagens personalizadas de erro aos seus usuários.
  • erro_msg: Um texto, em português contendo uma breve explicação do erro, que pode ser implementada diretamente aos usuários como resposta de erro de utilização ou comunicação.
  • response: Um objeto que compõe o conjunto de resultados da consulta de cep realizadas, cada chave/valor retornado tem também um significado, e é diretamente utilizado como corpo da resposta. Como segue:
    • registros: O número de respostas de objetos de CEP retornados no conjunto de resultados, 0 caso o cep que tenha sido informado não seja localizado. O método GET exige um numero de CEP e retorna um conjunto com 1 (um) único resultado. Outros métodos podem retornar conjuntos paginados e uma quantidade maior de resultados.
    • dados: conjunto de resultado do retorno, contendo os dados da consulta, ou um resultado vazio para os campos que não possuem informação relevante. Como segue:
      • data_atualizacao: Data onde o CEP foi atualizado pelos correios, ou pelo DNE (Departamento Nacional de Endereçamento.
      • cep: o Código de Endereçamento Postal que foi consultado, somente os digitos numéricos
      • tipo: o TIPO pode ser de 5 valores textuais diferentes, onde:
        CEP COMUM um código de CEP pertencente a um logradouro, ou parte de um logradouro.
        CEP ÚNICO um cep único para localidades não codificadas por ruas e endereços, como cidades ou bairros.
        AGENCIAS CORREIOS indicam que o CEP pertence a uma unidade dos Correios, ou endereços destinados ao manuseio ou entrega/retirada de mercadorias oriundas dos serviços postais prestados pelos correios.
        GRANDES CLIENTES indicam ceps que pertencem a Grandes Utilizadores ou centralizadoras como Caixas Postais ou unidades tratadas de maneira especial, que podem possuir regras próprias e prazos de entrega diferentes para os serviços postais, ou regras de identificação de usuário/destinatário final diferente do padrão de endereçamento usado pelos logradouros, como a identificação exclusiva do usuário/destinatario final.
        OUTROS são CEPS que podem ser de uso único ou temporário, como para uma promoção ou podem ter alguma outra tratativa especial por parte dos correios, e que podem sofrer alterações sem aviso prévio.
      • logradouro_completo: O logradouro final que o CEP se refere, como por exemplo uma parte de uma Rua ou Avenida, ou sua totalidade, numerações específicas que usam o CEP para grandes usuários ou prédios, etc.
      • logradouro: O logradouro a ser preenchido pelo usuário (utilizado no preenchimento automático)
      • complemento: Caso exista, indica que o logradouro pode ter outro sufixo de CEP para usuários/destinatarios diferentes. P.Ex numerais pares ou impares, até um numero ou combinação destes.
      • unidade: em casos de ceps de GRANDES USUARIOS ou AGENCIAS CORREIOS indicam qual o nome da unidade ao qual o cep se referencia. Em outros casos, indica parte do logradouro usada no endereçamento.
      • bairro: representam o nome do bairro ou distrito ao qual aquele CEP se referencia, sendo somente um dado informetivo ou complementar, já que não existe legislação específica para determinar ou delimitar bairros e distritos
      • cidade: indicam o municipio ao qual o CEP se representa, o nome segue a grafia oficial, algumas podem ter dados relativos a identificação tradicional, geralmente apresentados entre parenteses (). Seguem a indicação de nomes do IBGE (Instituto Brasileiro de Geografia e Estatística).
      • uf: Indicam a sigra da Unidade Federada ou estado no Brasil.
      • pais: sempre retorna Brasil.

Validação do CEP

Quando consultado um CEP de formato inválido, por exemplo: "024500000" (9 dígitos), ou "5010A40" (alfanumérico), ou "21373 010" (espaço), o código de retorno da consulta será uma mensagem de erro (Bad Request). Antes de realizar a chamada ao webservice, é de responsabilidade do desenvolvedor avaliar o formato do CEP e garantir que o mesmo possua exatos {8} dígitos numéricos, representados de maneira literal (string).
Quando um CEP de formato válido, para este padrão, porém inexistente, como: "22222-222", o retorno conterá um valor de "erro" igual a "true", e o response contará a informação de registros = 0. Os dados dos demais campos retornados serão sempre vazios ''. O que significa que o CEP consultado não foi encontrado na base de dados, ou que ainda não foi atualizado pelo sistema DNE dos correios.
Se é um número válido, ou recém criado, geralmente na primeira semana do mês seguinte, os CORREIOS atualizam e disponibilizam os dados dos novos cadastros para consulta pública, e atualizam a base DNE, nestes casos, em poucos dias a API BRASAP - CONSULTA CEP já se atualiza de maneira dinâmica, não havendo necessidade de submeter os novos CEPs para cadastro ou para atualização. Do mesmo modo se houverem atualizações de nomes de ruas ou mudanças, o período de transição dos correios é de 90 dias, aceitando os dados antigos ou atualizados, neste espaço de tempo (geralmente de 30 a 60 dias) o retorno da API é também atualizado, o que significa que sempre, os dados retornados são seguros para identificarem o endereço final de objetos e serviços postais, não havendo necessidade de edição por parte do usuário final da API ou dos serviços de entrega dos correios ou de outras que trabalhem dentro das especificações de endereçamento do DNE.

Módulos, Classes e Exemplos

Caso tenha desenvolvido algum pacote em alguma linguagem de programação específica, para o consumo dos dados dessa API, e queira compartilhar, ou queira participar do nosso GRUPO DEVELOPERS BRASIL no WHATSAPP acesse o link e mande o seu conteúdo.
Caso precise dos dados do BANCO DE DADOS DE CEP atualizados utilizados pela nossa API, você pode adquiri-lo através do link

CLIQUE E ADQUIRA NOSSA BASE DE DADOS EM MAIS DE 50 FORMATOS COMPATIVEIS

Exemplos de Implementação de CONSUMO DA API

JAVA SCRIPT - JQUERY

var settings = {
  "url": "https://consultacep.brasap.com.br/api/cep/01031970",
  "method": "GET",
  "timeout": 0,
};

$.ajax(settings).done(function (response) {
  console.log(response);
});

C# - RESTSharp

var client = new RestClient("https://consultacep.brasap.com.br/api/cep/01031970");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);

JAVA - OkHttp

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
Request request = new Request.Builder()
  .url("https://consultacep.brasap.com.br/api/cep/01031970")
  .method("GET", null)
  .build();
Response response = client.newCall(request).execute();
                

PHP 7/8 - CURL

                $curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://consultacep.brasap.com.br/api/cep/01031970',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
                

Python - Requests

import requests
url = "https://consultacep.brasap.com.br/api/cep/01031970"
payload={}
headers = {}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)
                

Swift iOS

import Foundation
#if canImport(FoundationNetworking)
import FoundationNetworking
#endif
var semaphore = DispatchSemaphore (value: 0)
var request = URLRequest(url: URL(string: "https://consultacep.brasap.com.br/api/cep/01031970")!,timeoutInterval: Double.infinity)
request.httpMethod = "GET"
let task = URLSession.shared.dataTask(with: request) { data, response, error in 
  guard let data = data else {
    print(String(describing: error))
    semaphore.signal()
    return
  }
  print(String(data: data, encoding: .utf8)!)
  semaphore.signal()
}
task.resume()
semaphore.wait()
                

Outras

COLOQUE SUA IMPLEMENTAÇÃO