Geolocalização com geocodebr"

In geocodebr: Geolocalização De Endereços Brasileiros (Geocoding Brazilian Addresses)

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  eval = identical(tolower(Sys.getenv("NOT_CRAN")), "true"),
  out.width = "100%"
)

Geocodificação: de endereços para coordenadas espaciais

Uma vez que você tenha uma tabela (data.frame) com endereços, a geolocalização dos dados com {geocodebr} pode ser feita em dois passos simples:

1. O primeiro passo é utilizar a função definir_campos() para declarar os nomes das colunas no seu data.frame que correspondem a cada campo dos endereços.

library(geocodebr)

# leitura de dados de input
input_df <- read.csv(system.file("extdata/small_sample.csv", package = "geocodebr"))

# 1o passo: indicar nome das colunas correspondento aos campos de endereço
fields <- geocodebr::definir_campos(
  logradouro = "nm_logradouro",
  numero = "Numero",
  cep = "Cep",
  localidade = "Bairro",
  municipio = "nm_municipio",
  estado = "nm_uf"
  )

1. O segundo passo é utilizar a função geocode() para encontrar as coordenadas geográficas dos endereços de entrada.

# 2o passo: geolocalização
df <- geocodebr::geocode(
  enderecos = input_df,
  campos_endereco = fields,
  resultado_completo = FALSE,
  verboso = TRUE,
  cache = TRUE,
  n_cores = 1
  )

head(df)

obs. Note que na primeira vez que o usuário usa essa fnução, {geocodebr} irá baixar alguns arquivos de referência e armaneza-los localmente. Assim, esses dados só precisam ser baixados uma única vez. Mais informações sobr o cache dos dados abaixo.

As coordendas espaciais do output usam sistema de referência ofical do Brasil: SIRGAS2000, CRS(4674). Os resultados do {geocodebr} são classificados em seis amplas categorias de precisão, dependendo de quão exatamente cada endereço de entrada foi correspondido com os dados do CNEFE. O grau de precisão é indicado em duas colunas da tabela de output: precisao e tipo_resultado. Mais informações abaixo.

Categorias de Precisão: precisao

Os resultados do {geocodebr} são classificados em seis amplas categorias de precisao:

• "numero"
• "numero_aproximado"
• "logradouro"
• "cep"
• "localidade"
• "municipio"
• NA (não encontrado)

Cada nível de precisão pode ser desagregado em tipos de correspondência mais refinados.

Tipo de Correspondência: tipo_resultado

A coluna tipo_resultado fornece informações mais detalhadas sobre como exatamente cada endereço de entrada foi encontrado no CNEFE. Em cada categoria, o {geocodebr} calcula a média da latitude e longitude dos endereços incluídos no CNEFE que correspondem ao endereço de entrada, com base em combinações de diferentes campos. No caso mais rigoroso, por exemplo, a função encontra uma correspondência determinística para todos os campos de um dado endereço ("estado", "municipio", "logradouro", "numero", "cep", "localidade"). Pense, por exemplo, em um prédio com vários apartamentos que correspondem ao mesmo endereço de rua e número. Nesse caso, as coordenadas dos apartamentos podem diferir ligeiramente, e o {geocodebr} calcula a média dessas coordenadas. Em um caso menos rigoroso, no qual apenas os campos ("estado", "municipio", "logradouro", "localidade") são encontrados, o {geocodebr} calcula as coordenadas médias de todos os endereços no CNEFE ao longo daquela rua e que se encontram na mesma localidade/bairro. Assim, as coordenadas de resultado tendem a ser o ponto médio do trecho daquela rua que passa dentro daquela localidade/bairro.

A lista completa dos níveis de precisão (precisao), suas categorias de tipo de correspondência (tipo_resultado) e os campos de endereço considerados em cada categoria estão descritos abaixo:

• precisao: "numero"

• tipo_resultado:

  • en01: logradouro, numero, cep e localidade
  • en02: logradouro, numero e cep
  • en03: logradouro, numero e localidade
  • en04: logradouro e numero
  • pn01: logradouro, numero, cep e localidade
  • pn02: logradouro, numero e cep
  • pn03: logradouro, numero e localidade
  • pn04: logradouro e numero

• precisao: "numero_aproximado"

• tipo_resultado:

  • ei01: logradouro, numero, cep e localidade
  • ei02: logradouro, numero e cep
  • ei03: logradouro, numero e localidade
  • ei04: logradouro e numero
  • pi01: logradouro, numero, cep e localidade
  • pi02: logradouro, numero e cep
  • pi03: logradouro, numero e localidade
  • pi04: logradouro e numero

• precisao: "logradouro" (quando o número de entrada está faltando 'S/N')

• tipo_resultado:

  • er01: logradouro, cep e localidade
  • er02: logradouro e cep
  • er03: logradouro e localidade
  • er04: logradouro
  • pr01: logradouro, cep e localidade
  • pr02: logradouro e cep
  • pr03: logradouro e localidade
  • pr04: logradouro

• precisao: "cep"

• tipo_resultado:

  • ec01: municipio, cep, localidade
  • ec02: municipio, cep

• precisao: "localidade"

• tipo_resultado:

  • eb01: municipio, localidade

• precisao: "municipio"

• tipo_resultado:
  • em01: municipio

Nota: As categorias de tipo_resultado que começam com 'p' utilizam correspondência probabilística do campo logradouro, enquanto os tipos que começam com 'e' utilizam apenas correspondência determinística. As categorias de tipo_resultado que usam correspondência probabilística ainda não estão implementados no pacote geocodebr.

Cache de Dados

Na primeira vez que o usuário executar a função geocode(), o {geocodebr} irá baixar alguns arquivos de referência e armazená-los localmente. Dessa forma, os dados precisam ser baixados apenas uma vez. Vale lembrar que esses arquivos requerem aproximadamente 4GB de espaço no seu disco local.

O pacote inclui as seguintes funções para ajudar os usuários a gerenciar os arquivos em cache:

• listar_pasta_cache(): retorna o caminho onde os dados em cache estão armazenados. Por padrão, os arquivos são armazenados no diretório do pacote.
• definir_pasta_cache(): define um diretório personalizado para ser utilizado. Essa configuração é persistente entre diferentes sessões do R.
• listar_dados_cache(): lista todos os arquivos atualmente armazenados em cache.
• deletar_pasta_cache(): exclui todos os arquivos do diretório de cache utilizado pelo {geocodebr}.

geocodebr documentation built on Aug. 8, 2025, 7:15 p.m.