Endereçamento Padrão Brasileiro

No Brasil, o endereçamento padrão é regido principalmente pelos Correios (Empresa Brasileira de Correios e Telégrafos), que segue normas internacionais da UPU (União Postal Universal) e diretrizes nacionais para garantir a entrega de correspondências.

Abaixo, detalhamos a composição, a modelagem de dados e as fontes oficiais para integração.

1. Composição Padronizada do Endereço

Segundo o Guia de Endereçamento dos Correios, um endereço completo no Brasil deve conter os seguintes elementos em ordem específica:

2. Modelagem de Banco de Dados

Para armazenar endereços de forma precisa e normalizada, a melhor prática é separar os componentes. Evite campos únicos como “Endereço Completo”, pois dificultam buscas e validações.

Sugestão de Estrutura Relacional:

Uma modelagem robusta separa o CEP (que contém os dados geográficos fixos) do Número e Complemento (que são específicos da instância do endereço).

• Tabela enderecos (ou usuarios_enderecos):

  • id (PK)

  • cep (VARCHAR 8 – Armazene apenas números)

  • logradouro (VARCHAR 100)

  • numero (VARCHAR 10 – Use VARCHAR para casos como “100-A” ou “Km 45”)

  • complemento (VARCHAR 50)

  • bairro (VARCHAR 50)

  • cidade (VARCHAR 50)

  • uf (CHAR 2)

  • codigo_ibge (INT – Crucial para emissão de notas fiscais e integração com órgãos públicos)

Dica Pro: Sempre armazene o Código IBGE do município. Ele é o identificador único “universal” no Brasil, usado pela Receita Federal, SEFAZ e sistemas de saúde.

3. Fontes Oficiais e Listagens

As fontes primárias de dados de endereçamento no Brasil são:

1. DNE (Diretório Nacional de Endereços): É a base oficial dos Correios. Ela é paga e atualizada periodicamente. É a única fonte 100% oficial para nomes de ruas e faixas de CEP.

2. IBGE (Instituto Brasileiro de Geografia e Estatística): Fonte oficial para a lista de Estados (UFs) e Municípios, além da hierarquia de distritos.

3. Governo Federal (Portal Gov.br): Disponibiliza catálogos de APIs e bases de dados abertas para interoperabilidade entre sistemas públicos.

4. APIs para Integração

Para integrar seu sistema e preencher endereços automaticamente a partir do CEP, existem opções oficiais (pagas) e alternativas amplamente utilizadas (gratuitas ou freemium):

Oficiais

• API Correios: Exige contrato comercial com os Correios. Oferece alta confiabilidade e dados sempre atualizados com a base DNE.

• Plataforma de Interoperabilidade (Gov.br): API voltada principalmente para órgãos públicos ou parceiros do governo para consulta ao Cadastro Base de Endereço.

Alternativas Populares (Baseadas no DNE/IBGE)

• ViaCEP: Gratuita, simples e sem necessidade de cadastro. Extremamente popular em formulários web.

• BrasilAPI: Moderna, de código aberto, agrega dados de múltiplas fontes (Correios, ViaCEP) e retorna inclusive coordenadas geográficas em alguns casos.

• CEP Aberto: Base colaborativa que oferece geolocalização (latitude e longitude) junto aos dados do endereço.

Sua intuição está corretíssima. Em sistemas de alta precisão (como ERPs, sistemas logísticos ou governamentais), o logradouro nunca deve ser um campo de texto livre único.

Se você armazenar “Rua das Flores” em um registro e “R. das Flores” em outro, sua busca por “Rua” falhará, e você terá duplicidades invisíveis. A separação granular é o que chamamos de Normalização de Endereço.

Aqui está como estruturar isso de forma profissional:

1. Onde encontrar as Listas Oficiais

Para evitar “inventar” abreviações, você deve usar as tabelas oficiais que o governo brasileiro e os Correios utilizam:

• DNE (Diretório Nacional de Endereços): É a “bíblia” dos Correios. Eles possuem uma tabela oficial de Tipos de Logradouro (ex: R, AV, PCA, AL) e suas respectivas descrições.

• eSocial (Tabela 20): O governo federal padronizou os tipos de logradouro para o sistema eSocial. É a lista mais acessível e atualizada para desenvolvedores.

• IBGE: No Censo, o IBGE utiliza uma classificação similar, mas a do eSocial/Correios é mais prática para sistemas transacionais.

Exemplo de Dados Reais (Baseado na Tabela 20 do eSocial):

2. Sugestão de Modelagem de Banco de Dados

Para o seu caso, o ideal é criar uma Tabela de Domínio para os tipos de logradouro. Isso garante integridade referencial.

Tabela tipo_logradouro (Dicionário)

Tabela enderecos (Granular)

3. Vantagens desta Estrutura

1. Buscas Precisas: Para listar todas as praças no RJ, sua query seria:

   SELECT * FROM enderecos WHERE tipo_logradouro_id = (SELECT id FROM tipo_logradouro WHERE sigla = 'PC') AND uf = 'RJ'.

2. Exibição Flexível: Você escolhe no Front-end se mostra “Rua Rio Branco” ou “R. Rio Branco” apenas concatenando os campos.

3. Validação: O usuário não consegue digitar “Rúa” (com acento) ou “Ruaa”, ele é forçado a selecionar uma opção válida.

4. Fontes com API para Integração

Se você quer buscar essas informações via código, aqui estão as melhores opções:

1. BrasilAPI (Recomendado): É a API mais moderna. Ela retorna o logradouro já separado em alguns provedores ou facilita a limpeza.

2. ViaCEP: É o padrão de mercado. Embora retorne o logradouro concatenado (ex: “Praça da Sé”), os dados seguem o padrão dos Correios, o que facilita criar um script de “split” baseado na sua tabela de tipos.

3. DataRio (Prefeitura do Rio): Já que você citou o Rio de Janeiro, o portal Data.rio possui uma API de logradouros específica da cidade com os códigos oficiais da prefeitura, nomes parciais e tipos separados.

Vamos montar um script SQL para criar essas tabelas já com os principais tipos de logradouro inseridos?

Script SQL

Excelente. Para implementar isso de forma profissional, vamos seguir o padrão oficial. A lista mais completa e utilizada para essa finalidade é a Tabela de Tipos de Logradouro do DNE (Diretório Nacional de Endereços) dos Correios.

Abaixo, apresento o script SQL para estruturar o banco de dados e os dados para popular a tabela de domínios.

1. Estrutura do Banco de Dados (PostgreSQL/MySQL)

Nesta modelagem, separamos o domínio (tipos válidos) da tabela de endereços.

-- 1. Tabela de Domínio: Tipos de Logradouro
CREATE TABLE tipo_logradouro (
    id SERIAL PRIMARY KEY,
    abreviatura VARCHAR(10) NOT NULL UNIQUE,
    extenso VARCHAR(50) NOT NULL
);

-- 2. Tabela de Endereços Normalizada
CREATE TABLE enderecos (
    id SERIAL PRIMARY KEY,
    tipo_logradouro_id INT REFERENCES tipo_logradouro(id),
    nome_logradouro VARCHAR(150) NOT NULL,
    numero VARCHAR(10),
    complemento VARCHAR(100),
    bairro VARCHAR(100),
    cidade VARCHAR(100),
    uf CHAR(2),
    cep CHAR(8),
    codigo_ibge INT
);

2. População da Tabela (Base Oficial DNE/eSocial)

Aqui estão os tipos mais comuns extraídos da lista oficial para você inserir no seu banco:

INSERT INTO tipo_logradouro (abreviatura, extenso) VALUES
('AL', 'Alameda'),
('AV', 'Avenida'),
('BC', 'Beco'),
('BL', 'Bloco'),
('CAM', 'Caminho'),
('EST', 'Estrada'),
('LGO', 'Largo'),
('LOT', 'Loteamento'),
('PC', 'Praça'),
('PRV', 'Prolongamento'),
('R', 'Rua'),
('ROD', 'Rodovia'),
('TV', 'Travessa'),
('VLA', 'Vila');

Nota: Existem mais de 70 tipos (como Aeroporto, Condomínio, Habitacional, etc.). Para uma aplicação geral, estes cobrem 95% dos casos.

3. Como ficariam suas Consultas (Queries)

Com essa estrutura, você resolve o problema de busca que mencionou:

• Para buscar todas as “Praças” (independentemente de como foi digitado):

  SQL

  SELECT e.* FROM enderecos e
  JOIN tipo_logradouro t ON e.tipo_logradouro_id = t.id
  WHERE t.abreviatura = 'PC'; -- Ou t.extenso = 'Praça'

• Para exibir o endereço completo formatado:

  SQL

  SELECT t.extenso || ' ' || e.nome_logradouro || ', ' || e.numero AS endereco_completo
  FROM enderecos e
  JOIN tipo_logradouro t ON e.tipo_logradouro_id = t.id;
  

4. Onde encontrar a lista completa e APIs

1. DNE (Correios): Se você comprar a base oficial, ela vem com um arquivo chamado LOG_TIPO_LOGRADOURO.TXT contendo todas as siglas.

2. IBGE (CNEFE): O Cadastro Nacional de Endereços para Fins Estatísticos (CNEFE) disponibiliza microdados com essa separação.

3. API de Apoio: A BrasilAPI ou a Postmon costumam retornar o logradouro já com o tipo no início. Você pode usar uma função de “Regex” ou “Split” no seu código para separar a primeira palavra (o tipo) e comparar com sua tabela tipo_logradouro.