API de CEP gratuita

A URL base da API segue o modelo: https://www.cepaberto.com/api/v3/metodo?parametro=valor[&parametro2=valor2]

• metodo especifica a busca a ser feita, atualmente os metodos suportados são cep, nearest, address, cities e update.
• parametro e valor dependem da requisição feita e serão descritos nas seções seguintes.
• Os resultados são retornados em formato JSON.

• Se nenhum CEP for encontrado com o valor buscado, o resultado será vazio, i.e.,

  {}

Dado um número de CEP busca os dados respectivos

• GET https://www.cepaberto.com/api/v3/cep
• Parametro aceito cep

Exemplo de busca pelos dados do CEP 01001000 em Python:

import requests

url = "https://www.cepaberto.com/api/v3/cep?cep=01001000"
# Substitua pelo seu token de acesso pessoal
headers = {'Authorization': 'Token token=SEU_TOKEN'}
response = requests.get(url, headers=headers)

print(response.json())

Resultado

Para o exemplo anterior, o resultado será:

{"cidade": {"ibge": "3550308", "nome": "São Paulo", "ddd": 11}, "estado": {"sigla": "SP"}, "altitude": 760.0, "longitude": "-46.636", "bairro": "Sé", "complemento": "- lado ímpar", "cep": "01001000", "logradouro": "Praça da Sé", "latitude": "-23.5479099981"}

Dado um par latitude e longitude, retorna-se o CEP mais próximo do ponto correspondente a estas coordenadas. A busca limita-se a um raio de 10km a partir do ponto referente as coordenadas passadas como parâmetro.

• GET https://www.cepaberto.com/api/v3/nearest
• Parametros aceitos lat e lng

Exemplo de busca pelas coordenadas -20.55,-43.63 em Python:

import requests

url = "https://www.cepaberto.com/api/v3/nearest"
# Substitua pelo seu token de acesso pessoal
headers = {'Authorization': 'Token token=SEU_TOKEN'}
params = {'lat': -20.55, 'lng': -43.63}
response = requests.get(url, headers=headers, params=params)

print(response.json())

Resultado

Para o exemplo anterior, o resultado será:

{"cidade": {"ibge": "3550308", "nome": "São Paulo", "ddd": 11}, "estado": {"sigla": "SP"}, "altitude": 760.0, "longitude": "-46.636", "bairro": "Sé", "complemento": "- lado ímpar", "cep": "01001000", "logradouro": "Praça da Sé", "latitude": "-23.5479099981"}

Dados os valores de estado (obrigatório), cidade (obrigatório), logradouro (opcional) e bairro (opcional), retorna-se o CEP referente. A pesquisa é feita com match exato para os valores de estado, cidade e bairro. Já para o logradouro, é feito um match LIKE . O logradouro não é um campo obrigatório, pois certas cidades e municípios possuem um CEP próprio, havendo ou não CEPs por logradouro.

• GET https://www.cepaberto.com/api/v3/address
• Parametros aceitos estado, cidade, bairro e logradouro

Exemplo de busca pelo CEP da cidade de Ubatuba, SP em Python:

import requests

url = "https://www.cepaberto.com/api/v3/address"
# Substitua pelo seu token de acesso pessoal
headers = {'Authorization': 'Token token=SEU_TOKEN'}
params = {'estado': 'SP', 'cidade': 'Ubatuba'}
response = requests.get(url, headers=headers, params=params)

print(response.json())

Resultado

Para o exemplo anterior, o resultado será:

{'latitude': '-23.4336578', 'longitude': '-45.0838481', 'estado': {'sigla': 'SP'}, 'cep': '11680000', 'cidade': {'nome': 'Ubatuba', 'ddd': 12, 'ibge': '3555406'}, 'altitude': 4.8}

Mas os nomes de certas cidades ou municípios nem sempre possuem grafia unificada. Ao pesquisar pelo município de "Santo Antônio da Estiva", estado do Amazonas, nenhum resultado será encontrado.

O problema é que tal município é escrito na base de dados do CEP Aberto como "Santo Antônio da Estiva (Pirajuí)", que está de acordo com a base dos Correios. Para evitar erro no valor da cidade passada como parâmetro, um novo endpoint foi adicionado a API do CEP Aberto, /cities/.

Para buscar pelos nomes de todas as cidades e municípios, de um certo estado, no banco de dados do CEP Aberto, basta passar a sigla do estado: https://www.cepaberto.com/api/v3/cities?estado=AM

Resultado

Para o exemplo anterior, o resultado será:

[
  {"nome":"Agrovila São Sebastião do Caburi (Parintins)"},
  {"nome":"Alvarães"},
  {"nome":"Amatari (Itacoatiara)"},
  {"nome":"Amaturá"},
  {"nome":"Anamã"},
  {"nome":"Anori"},
  {"nome":"Apuí"},
  {"nome":"Araras (Caapiranga)"}, ...
]

Com este resultado disponível, resta ao usuário da API apenas conhecer logradouro (e bairro) para fazer busca pelo CEP.

Atualiza automaticamente os CEPs informados. Caso você tenha CEPs que não estão disponíveis no CEP Aberto, ou que não estão com a informação em dia, você pode atualizá-los através da API. Para proteger os serviços externos de consulta, cada token pode tentar atualizar até 5 CEPs por dia, dentro do limite global de 20 CEPs por dia:

• POST https://www.cepaberto.com/api/v3/update
• Parametro aceito ceps

Exemplo de atualização de 3 CEPs 32371380,32210180,36420000 em Python. Os valores no parâmetro ceps são separados por vírgula. O número máximo aceito é 5 por requisição e valores repetidos são considerados apenas uma vez.

import requests

url = "https://www.cepaberto.com/api/v3/update"
# Substitua pelo seu token de acesso pessoal
headers = {'Authorization': 'Token token=SEU_TOKEN'}
data = {'ceps': ",".join(['32371380', '41400120', '36420000'])}
response = requests.post(url, data=data, headers=headers)

print(response.json())

Limite diário

Se o lote não couber integralmente na cota restante, nenhum CEP será processado e a API responderá com HTTP 429. O cabeçalho Retry-After informa quantos segundos faltam até a renovação da cota, à meia-noite no horário de Brasília. CEPs inexistentes e falhas dos provedores também consomem a cota.

Resultado

Para o exemplo anterior, o resultado será a lista de CEPs que foram atualizados com sucesso, repare que o último CEP não existe, então não será atualizado:

[32371380,41400120]

Registre-se gratuitamente ou entre na sua conta para obter seu token pessoal. Substitua SEU_TOKEN nos exemplos. Envie o token no cabeçalho HTTP Authorization.

Inicialmente, a API tem um limite de requisições por intervalo de tempo. Este limite existe para inibir possiveis bots que possam comprometer o tempo de resposta. Atualmente, o intervalo entre requisições é de 1 segundo. Requisições mais frequentes resultarão em HTTP Error 403 Forbidden. O limite máximo de requisições é de 10 mil por dia. Respeite os limites do serviço e aguarde antes de tentar novamente.