enderecopadrao: padronizador de endereços brasileiros • enderecopadrao

enderecopadrao é 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

O pacote ainda não se encontra no CRAN. Para baixar a última versão estável, use o código abaixo:

# install.packages("remotes")
remotes::install_github("ipeaGIT/enderecopadrao@v0.1.0")

Para baixar a versão em desenvolvimento, use o seguinte código:

remotes::install_github("ipeaGIT/enderecopadrao")

Utilização

O pacote fornece funções para padronizar diferentes campos de um endereço. A padronizar_enderecos() padroniza diversos campos simultaneamente, recebendo, para isso, um dataframe e uma relação de correspondência entre as colunas desse dataframe e os campos a serem padronizados:

library(enderecopadrao)

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

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

padronizar_enderecos(enderecos, campos_do_endereco = campos)
#>                      logradouro numero complemento       cep          bairro
#>                          <char> <char>      <char>    <char>          <char>
#> 1: RUA NOSSA SENHORA DA PIEDADE     20   QUADRA 20 25220-020 JARDIM BOTANICO
#>         municipio         estado
#>            <char>         <char>
#> 1: RIO DE JANEIRO RIO DE JANEIRO

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. Na prática, no entanto, essa função é opcional, e poderíamos passar um vetor de caracteres no argumento campos_do_endereco (a correspondencia_campos() realiza alguns testes no input, garantindo que o vetor a ser passado pra padronizar_enderecos() esteja corretamente formatado).

Por trás dos panos, a padronizar_enderecos() utiliza 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:

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. Nese caso, a função ainda 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 com vetores numéricos e de strings.

estados <- c("21", " 21", "MA", " MA ", "ma", "MARANHÃO")
padronizar_estados(estados)
#> [1] "MARANHAO" "MARANHAO" "MARANHAO" "MARANHAO" "MARANHAO" "MARANHAO"

estados <- c(21, 32)
padronizar_estados(estados)
#> [1] "MARANHAO"       "ESPIRITO SANTO"

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 são aplicadas 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)
#> [1] "RIO DE JANEIRO" "RIO DE JANEIRO" "RIO DE JANEIRO" "RIO DE JANEIRO"
#> [5] "RIO DE JANEIRO" "SAO PAULO"

municipios <- 3304557
padronizar_municipios(municipios)
#> [1] "RIO DE JANEIRO"

municipios <- c("PARATI", "MOJI MIRIM")
padronizar_municipios(municipios)
#> [1] "PARATY"     "MOGI MIRIM"

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)
#> [1] "PARQUE INDUSTRIAL"       "NOSSA SENHORA DE FATIMA"
#> [3] "ILHA DO GOVERNADOR"      "VILA OLIMPICA"          
#> [5] "NUCLEO RESIDENCIAL"

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 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)
#> [1] "22290-140" "22290-140" "22290-140" "22290-140"

ceps <- c(22290140, 1000000)
padronizar_ceps(ceps)
#> [1] "22290-140" "01000-000"

padronizar_ceps("2229014a")
#> Error in `padronizar_ceps()`:
#> ! CEP não deve conter letras.
#> ℹ O elemento com índice 1 possui letras.

padronizar_ceps("022290140")
#> Error in `padronizar_ceps()`:
#> ! CEP não deve conter mais que 8 dígitos.
#> ℹ O elemento com índice 1 possui mais que 8 dígitos após padronização.

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)
#> [1] "RUA GENERAL GLICERIO, 137"                                    
#> [2] "CONDOMINIO PRESIDENTE JUSCELINO KUBITSCHEK, QUADRA 5 LOTE 2 1"
#> [3] "AVENIDA DOM PEDRO I, 20"

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. 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”.

numeros <- c("0210", "001", "1", "S N", "S/N", "SN", "0180  0181")
padronizar_numeros(numeros)
#> [1] "210"     "1"       "1"       "S/N"     "S/N"     "S/N"     "180 181"

numeros <- c(210, 1, 10000)
padronizar_numeros(numeros)
#> [1] "210"   "1"     "10000"

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)
#> [1] "QUADRA 1 LOTE 2 CASA 3"   "APARTAMENTO 405"         
#> [3] "PROXIMO CAIXA POSTAL 450"