Introdução ao geocodebr

1. Geolocalização: de endereços para coordenadas espaciais

Uma vez que você possui uma tabela de dados (data.frame) com endereços no Brasil, a geolocalização desses dados pode ser feita em apenas dois passos:

1. O primeiro passo é usar a função definir_campos() para indicar os nomes das colunas no seu data.frame que correspondem a cada campo dos endereços.
2. O segundo passo é usar a função geocode() para encontrar as coordenadas geográficas dos endereços de input.

library(geocodebr)
library(sf)

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

# Primeiro passo: inidicar o nome das colunas com cada campo dos enderecos
campos <- geocodebr::definir_campos(
  logradouro = "nm_logradouro",
  numero = "Numero",
  cep = "Cep",
  localidade = "Bairro",
  municipio = "nm_municipio",
  estado = "nm_uf"
)

# Segundo passo: geolocalizar
df <- geocodebr::geocode(
  enderecos = input_df,
  campos_endereco = campos,
  resultado_completo = FALSE,
  resolver_empates = FALSE,
  resultado_sf = FALSE,
  verboso = FALSE,
  cache = TRUE,
  n_cores = 1
)

Nota: A função geocode() requer que os dados do CNEFE estejam armazenados localmente. A primeita vez que a função é executada, ela baixa os dados do CNEFE e salva em um cache local na sua máquina. No total, esses dados somam cerca de 3 GB, o que pode fazer com que a primeira execução da função demore. Esses dados, no entanto, são salvos de forma persistente, logo eles são baixados uma única vez. Ver abaixo mais informações sobre o cache de dados.

Os resultados do {geocodebr} são classificados em seis categorias gerais de precisao, dependendo do nível de exatidão com que cada endereço de input foi encontrado nos dados do CNEFE. Para mais informações, consulte a documentação da função ou a vignette “geocode”.

2. Geolocalização reversa: de coordenadas espaciais para endereços

A função geocode_reverso(), por sua vez, permite a geolocalização reversa, ou seja, a busca de endereços próximos a um conjunto de coordenadas geográficas. Mais detalhes na vignette “geocode”.

# amostra de pontos espaciais
pontos <- readRDS(
  system.file("extdata/pontos.rds", package = "geocodebr")
)

# seleciona somente os primeiros 20 pontos
pontos <- pontos[1:20,]

# geocode reverso
df_enderecos <- geocodebr::geocode_reverso(
  pontos = pontos,
  dist_max = 1000,
  verboso = FALSE,
  n_cores = 1
)

3. Busca por CEPs

Por fim, a função busca_por_cep() permite fazer consultas de CEPs para encontrar endereços associados a cada CEP. A função recebe um vetor de CEPs e retorna um data.frame com os endereços e as coordenadas geográficas de cada CEP.

# amostra de CEPs
ceps <- c("70390-025", "20071-001")

df_ceps <- geocodebr::busca_por_cep(
  cep = ceps,
  resultado_sf = FALSE,
  verboso = FALSE
)