enderecobr: padronizador de endereços brasileiros"

In enderecobr: Padronizador de Endereços Brasileiros (Brazilian Addresses Standardizer)

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

enderecobr é um pacote de R que permite padronizar endereços brasileiros a partir de diferentes critérios. Os métodos de padronização atualmente incluem apenas manipulações de strings, não oferecendo suporte a correspondências probabilísticas entre strings.

Instalação

A última versão estável pode ser baixada do CRAN com o comando a seguir:

install.packages("enderecobr")

Caso prefira, a versão em desenvolvimento também pode ser usada. Para isso, use o seguinte comando:

# install.packages("remotes")
remotes::install_github("ipeaGIT/enderecobr")

Utilização

O enderecobr disponibiliza funções para padronizar os diversos campos de um endereço. Essas funções agem tanto sobre campos individuais quanto sobre um conjunto de campos. Vamos ver, primeiro, como funcionam as funções que agem sobre múltiplos campos simultaneamente.

Padronização de múltiplos campos simultaneamente

A padronizar_enderecos(), carro-chefe do pacote, atua de forma simultânea sobre os vários campos que podem compor um endereço. Para isso, ela recebe um dataframe e a correspondência entre suas colunas e os campos a serem padronizados:

library(enderecobr)

enderecos <- data.frame(
  id = 1,
  tipo = "r",
  logradouro = "ns sra da piedade",
  nroLogradouro = 20,
  complemento = "qd 20",
  cep = 25220020,
  bairro = "jd botanico",
  codmun_dom = 3304557,
  uf_dom = "rj"
)

campos <- correspondencia_campos(
  tipo_de_logradouro = "tipo",
  logradouro = "logradouro",
  numero = "nroLogradouro",
  complemento = "complemento",
  cep = "cep",
  bairro = "bairro",
  municipio = "codmun_dom",
  estado = "uf_dom"
)

padronizar_enderecos(enderecos, campos_do_endereco = campos)

Note que no exemplo acima nós também utiliza a função correspondencia_campos(), que facilita o processo de especificação de correspondência entre as colunas do dataframe e os campos do endereço a serem padronizados. Com ela, nós especificamos que a coluna que contém a informação de tipo de logradouro se chama "tipo", que a coluna de número do logradouro se chama "nroLogradouro", etc. Na prática, no entanto, essa função é opcional, e poderíamos simplesmente passar um vetor de caracteres no formato c(tipo_de_logradouro = "tipo", logradouro = "logradouro", ...). A correspondencia_campos(), no entanto, realiza alguns testes no input, garantindo que o vetor a ser passado pra padronizar_enderecos() esteja corretamente formatado.

A padronizar_enderecos() contém, ainda, cinco parâmetros adicionais. O formato_estados e o formato_numeros controlam como os estados e números padronizados, respectivamente, devem ser formatados. Caso formato_estados seja "por_extenso" (valor padrão), a função retorna o nome dos estados por extenso; caso seja "sigla", os estados são padronizados conforme suas respectivas siglas. Por sua vez, caso formato_numeros seja "character", a função retorna os números padronizados como caracteres, preservando valores como "S/N", que possuem letras e outros dígitos que não podem ser convertidos para valores numéricos; caso seja "integer", no entanto, os números são retornados como valores inteiros. Caso algum valor não possa ser convertido para inteiro, a função o substitui por NA e lança um warning alertando sobre a situação. Os exemplos a seguir demonstram esses parâmetros detalhadamente:

campos <- correspondencia_campos(
  numero = "nroLogradouro",
  estado = "uf_dom"
)

padronizar_enderecos(
  enderecos[, c("nroLogradouro", "uf_dom")],
  campos,
  formato_estados = "por_extenso",
  formato_numeros = "character"
)

padronizar_enderecos(
  enderecos[, c("nroLogradouro", "uf_dom")],
  campos,
  formato_estados = "sigla",
  formato_numeros = "integer"
)

# o exemplo abaixo gera um warning, pois o número não pode ser convertido para
# inteiro de forma adequada

padronizar_enderecos(
  data.table::data.table(numero = "12A 13B"),
  correspondencia_campos(numero = "numero"),
  formato_numeros = "integer"
)

O manter_cols_extras determina as colunas incluídas no output da função. Caso seja TRUE (valor padrão), todas as colunas do dataframe original são mantidas; caso seja FALSE, apenas as colunas usadas na padronização e seus respectivos resultados são preservados. O bloco abaixo demonstra essa funcionalidade:

campos <- correspondencia_campos(
  tipo_de_logradouro = "tipo",
  logradouro = "logradouro"
)

padronizar_enderecos(enderecos, campos, manter_cols_extras = TRUE)

padronizar_enderecos(enderecos, campos, manter_cols_extras = FALSE)

O combinar_logradouro, por sua vez, determina se os campos que compõem o logradouro (tipo, nome e número) devem ser combinados em um único campo padronizado de logradouro completo. Caso seja FALSE(valor padrão), os campos permanecem separados; se for TRUE, são combinados. Nesse caso, o parâmetro logradouro da correspondencia_campos() deve ser interpretado como o nome do logradouro. A seguir, demonstramos essa funcionalidade:

enderecos <- data.frame(
  tipo = "r",
  logradouro = "ns sra da piedade",
  nroLogradouro = 20
)

campos <- correspondencia_campos(
  tipo_de_logradouro = "tipo",
  logradouro = "logradouro",
  numero = "nroLogradouro"
)

padronizar_enderecos(enderecos, campos, combinar_logradouro = FALSE)

padronizar_enderecos(enderecos, campos, combinar_logradouro = TRUE)

O quinto parâmetro, checar_tipos, tem efeito apenas quando combinar_logradouro é TRUE, e deve ser usado para sinalizar se a ocorrência de duplicatas entre os tipos e nomes de logradouros deve ser verificada ao combiná-los (por exemplo, quando o tipo é descrito como "RUA" e o nome como "RUA BOTAFOGO"). Caso seja FALSE (valor padrão), a verificação não é feita; se for TRUE, a verificação é realizada e valores duplicados são removidos, como apresentado a seguir:

enderecos <- data.frame(
  tipo = "r",
  logradouro = "r ns sra da piedade",
  nroLogradouro = 20
)

padronizar_enderecos(
  enderecos,
  campos,
  combinar_logradouro = TRUE,
  checar_tipos = FALSE
)

padronizar_enderecos(
  enderecos,
  campos,
  combinar_logradouro = TRUE,
  checar_tipos = TRUE
)

Os parâmetros combinar_logradouro e checar_tipos acionam, de forma oculta, outra função que lida com múltiplos campos simultaneamente: a padronizar_logradouros_completos(). Essa função também pode ser usada de forma separada e, de forma similiar à padronizar_enderecos(), recebe um dataframe com as informações do logradouro (tipo, nome e número) e a correspondência entre suas colunas e os campos a serem padronizados:

campos <- correspondencia_logradouro(
  tipo_de_logradouro = "tipo",
  nome_do_logradouro = "logradouro",
  numero = "nroLogradouro"
)

padronizar_logradouros_completos(enderecos, campos_do_logradouro = campos)

Note que, nesse caso, usamos a função campos_do_logradouro() para estabelecer a correspondência entre colunas e campos do endereço, mas também poderíamos passar um vetor de caracteres no argumento campos_do_logradouro. A padronizar_logradouros_completos() também inclui os parâmetros manter_cols_extras e checar_tipos, que funcionam de forma idêntica aos parâmetros de mesmo nome da padronizar_enderecos().

Padronização de campos individuais

Por trás dos panos, tanto a padronizar_enderecos() quanto a padronizar_logradouros_completos() utilizam diversas outras funções que padronizam campos de forma individual. Cada uma delas recebe um vetor com valores não padronizados e retorna um vetor de mesmo tamanho com os respectivos valores padronizados. As funções atualmente disponíveis são:

• padronizar_estados()
• padronizar_municipios()
• padronizar_bairros()
• padronizar_ceps()
• padronizar_logradouros()
• padronizar_numeros()
• padronizar_tipos_de_logradouro()
• padronizar_complementos()

A padronizar_estados() aceita vetores de strings e números. Caso numérico, o vetor deve conter o código do IBGE de cada estado. Caso seja composto de strings, o vetor pode conter a sigla do estado, seu código ou seu nome por extenso. O parâmetro formato controla como o output deve ser padronizado, se conforme a sigla de cada estado ("sigla") ou se conforme seu nome por extenso ("por_extenso", valor padrão). Quando recebe um vetor de strings, a função aplica diversas manipulações para chegar a um valor padronizado, como a conversão de caracteres para caixa alta, remoção de acentos e caracteres não ASCII e remoção de espaços em branco antes e depois dos valores e de espaços em excesso entre palavras. O código abaixo apresenta exemplos de aplicação da função.

estados <- c("21", " 21", "MA", " MA ", "ma", "MARANHÃO")
padronizar_estados(estados)

padronizar_estados(estados, formato = "sigla")

estados <- c(21, 32)
padronizar_estados(estados)

A função de padronização de campos de município, padronizar_municipios(), funciona de forma muito semelhante, aceitando também valores numéricos representando os códigos dos municípios e strings. As mesmas manipulações de remoção de espaços, conversão para caixa alta e conversão para caracteres são aplicadas (assim como nos demais tratamentos de vetores de strings que serão apresentados a seguir), mas a função também verifica erros ortográficos frequentemente observados nos nomes dos municípios (e.g. Moji Mirim -> Mogi Mirim, Parati -> Paraty).

municipios <- c(
  "3304557", "003304557", " 3304557 ", "RIO DE JANEIRO", "rio de janeiro",
  "SÃO PAULO"
)
padronizar_municipios(municipios)

municipios <- 3304557
padronizar_municipios(municipios)

municipios <- c("PARATI", "MOJI MIRIM")
padronizar_municipios(municipios)

A padronizar_bairros() trabalha exclusivamente com vetores de strings. Como os nomes de bairros são muito mais variados e, consequentemente, menos rigidamente controlados do que os de estados e municípios, a função se atém a corrigir erros ortográficos e a expandir abreviações frequentemente utilizadas através de diversas expressões regulares (regexes). O exemplo abaixo mostra algumas das muitas abreviações usualmente empregadas no preenchimento de endereços.

bairros <- c(
  "PRQ IND",
  "NSA SEN DE FATIMA",
  "ILHA DO GOV",
  "VL OLIMPICA",
  "NUC RES"
)
padronizar_bairros(bairros)

A padronizar_ceps() é outro exemplo de função que trabalha com strings e números. Caso o input seja numérico, a função verifica se os valores possuem comprimentos compatíveis com um CEP, adicionando zeros à esquerda se necessário (é muito comum que leitores de CSV, por exemplo, erroneamente leiam valores de CEP como números e excluam zeros à esquerda por considerá-los redundantes). Caso o input seja formado por strings, a função remove caracteres que frequentemente são usados para separar partes do CEP (e.g. pontos, vírgulas, espaços em branco) e verifica se o hífen separando os cinco primeiros dígitos dos três últimos está presente, adicionando-o caso contrário. A função ainda produz erros se recebe como input valores que não podem ser corretamente convertidos em CEPs, como no caso de strings contendo caracteres não numéricos e de strings com caracteres em excesso.

ceps <- c("22290-140", "22.290-140", "22290 140", "22290140")
padronizar_ceps(ceps)

ceps <- c(22290140, 1000000)
padronizar_ceps(ceps)

padronizar_ceps("2229014a")

padronizar_ceps("022290140")

A tarefa de padronizar logradouros é a mais complexa dentre as apresentadas até aqui, uma vez que o campo de logradouro é o que apresenta maior variabilidade de input. A padronizar_logradouros(), portanto, assim como a função de padronização de bairros, se limita a expandir abreviações frequentemente utilizadas e a corrigir alguns poucos erros de digitação, fora o tratamento usual dado a strings, como conversão para caixa alta, remoção de espaços em excesso e antes e depois das strings, etc.

logradouros <- c(
  "r. gen.. glicério, 137",
  "cond pres j. k., qd 05 lt 02 1",
  "av d pedro I, 020"
)
padronizar_logradouros(logradouros)

A padronizar_numeros() tem como objetivo padronizar o número do logradouro, caso este esteja em um campo separado do logradouro propriamente dito. A função aceita vetores de números e strings e retorna um vetor de strings ou inteiros, a depender do parâmetro formato (que pode receber os valores "character" e "integer", auto-explicativos). Os tratamentos incluem a remoção de zeros à esquerda, remoção de espaços em branco em excesso e a substituição de variações de SN (sem número) por "S/N". Note que o equivalente de "S/N" quando o output é numérico é NA. Valores que não puderem ser adequadamente convertidos para inteiro também são substituídos por NA, o que é sinalizado por um warning.

numeros <- c("0210", "001", "1", "S N", "S/N", "SN", "0180  0181")
padronizar_numeros(numeros)

# o exemplo abaixo gera um warning, pois "0180 0181" não pode ser adequadamente
# convertido para um único valor inteiro - as variações de S/N, por sua vez, já
# seriam convertidas para NA
numeros <- c("0210", "001", "1", "S N", "S/N", "SN", "0180  0181")
padronizar_numeros(numeros, formato = "integer")

numeros <- c(210, 1, 10000)
padronizar_numeros(numeros)

Outra função que atua sobre uma informação específica do logradouro, caso essa seja fornecida separadamente, é a padronizar_tipos_de_logradouro(). Fora o tratamento usual dado a strings, a função também expande abreviações frequentemente observadas no campo de tipo de logradouro.

tipos <- c("r", "R.", "AVN", "AVE", "JDM", "QD")
padronizar_tipos_de_logradouro(tipos)

Por fim, a padronizar_complementos() age de forma similar às funções de padronização de logradouros e bairros, porém agindo de forma mais específica em abreviações e observações frequentemente observados na especificação de complementos de logradouros.

complementos <- c("QD1 LT2 CS3", "APTO. 405", "PRX CX POST 450")
padronizar_complementos(complementos)

Controle de verbosidade

O disparo de mensagens com informações sobre a execução das funções pode ser controlado pela opção enderecobr.verbose, que recebe os valores "quiet" ou "verbose", como demonstrado a seguir:

campos <- correspondencia_logradouro(
  nome_do_logradouro = "logradouro",
  numero = "nroLogradouro"
)

# quieto, por padrão
res <- padronizar_logradouros_completos(enderecos, campos)

# verboso, se desejado
rlang::local_options("enderecobr.verbose" = "verbose")
res <- padronizar_logradouros_completos(enderecos, campos)
#> ✔ Padronizando nomes dos logradouros... [130ms]
#> ✔ Padronizando números... [111ms]
#> ✔ Trazendo números para o logradouro completo... [107ms]

enderecobr documentation built on April 3, 2025, 8:40 p.m.