API para Desenvolvedores

Visão Geral

A API do CepRua é gratuita, pública e sem necessidade de autenticação. Retorna dados de endereços brasileiros no formato JSON.

Base URL https://ceprua.com.br/api

GET Busca por CEP

Retorna os dados de um endereço a partir de um CEP específico.

GET /api/cep/{cep}

Parâmetros

Parâmetro	Tipo	Descrição
`cep`	string	CEP com ou sem hífen (ex: `01310-100` ou `01310100`)

Exemplo de requisição

cURL

curl "https://ceprua.com.br/api/cep/01310-100"

GET Busca por texto

Pesquisa logradouros pelo nome da rua, avenida ou CEP parcial.

GET /api/buscar?q={termo}

Parâmetros de query

Parâmetro	Tipo	Obrigatório	Descrição
`q`	string	sim	Termo de busca (mínimo 3 caracteres)

Exemplo de requisição

cURL

curl "https://ceprua.com.br/api/buscar?q=Paulista"

Resposta JSON

Todas as respostas seguem o mesmo formato:

JSON - Busca por CEP

{
  "cep": "01310-100",
  "logradouro": "Avenida Paulista",
  "bairro": "Bela Vista",
  "cidade": "São Paulo",
  "uf": "SP",
  "ibge": "3550308",
  "url": "https://ceprua.com.br/sp/sao-paulo/bela-vista/avenida-paulista"
}

JSON - Busca por texto

{
  "resultados": [
    {
      "cep": "01310-100",
      "logradouro": "Avenida Paulista",
      "bairro": "Bela Vista",
      "cidade": "São Paulo",
      "uf": "SP",
      "url": "https://ceprua.com.br/sp/sao-paulo/bela-vista/avenida-paulista"
    }
  ],
  "total": 1
}

Campos da resposta

Campo	Tipo	Descrição
`cep`	string	CEP formatado com hífen
`logradouro`	string	Nome da rua ou avenida
`bairro`	string	Nome do bairro
`cidade`	string	Nome do município
`uf`	string	Sigla do estado (2 letras)
`ibge`	string	Código IBGE do município
`url`	string	URL da página do endereço no CepRua

Erros

HTTP Status	Significado
200	Sucesso
404	CEP não encontrado
422	Parâmetro inválido (CEP mal formatado ou query muito curta)
429	Limite de requisições atingido

Exemplos de código

JavaScript (fetch)

async function buscarCep(cep) {
  const res = await fetch(`https://ceprua.com.br/api/cep/${cep}`);

  if (!res.ok) {
    throw new Error(`CEP não encontrado (status ${res.status})`);
  }

  const data = await res.json();
  console.log(data);
  return data;
}

// Uso:
buscarCep('01310-100').then(console.log);

PHP

function buscarCep(string $cep): array {
    $url = 'https://ceprua.com.br/api/cep/' . urlencode($cep);
    $response = file_get_contents($url);

    if ($response === false) {
        throw new RuntimeException('Erro ao consultar o CEP.');
    }

    return json_decode($response, true);
}

// Uso:
$endereco = buscarCep('01310-100');
print_r($endereco);

Python

import requests

def buscar_cep(cep: str) -> dict:
    url = f"https://ceprua.com.br/api/cep/{cep}"
    response = requests.get(url)
    response.raise_for_status()
    return response.json()

# Uso:
endereco = buscar_cep("01310-100")
print(endereco)

Limites de uso

Uso justo (Fair Use)

A API é pública e gratuita, mas pedimos que seja utilizada de forma responsável. Em caso de uso intensivo, entre em contato para discutirmos uma solução adequada.

Sem autenticação necessária para uso normal
Rate limit automático para abusos
Cache no lado do cliente é altamente recomendado
Não utilize para scraping massivo do banco de dados