Introdução ao geocodebr

Geolocalização refere-se ao ato de encontrar um ponto no espaço, geralmente representado por um par de coordenadas, a partir de um determinado endereço. O geocodebr permite geolocalizar endereços brasileiros de forma simples e eficiente e sem limite de número de consultas, a partir de dados públicos de endereços do Brasil. A principal base de referência é o Cadastro Nacional de Endereços para Fins Estatísticos (CNEFE), um conjunto de dados coletado e publicado pelo Instituto Brasileiro de Geografia e Estatística (IBGE) que contém os endereços de mais de 110 milhões de domicílios e estabelecimentos do país.

Instalação

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

install.packages("geocodebr")

Caso prefira, a versão em desenvolvimento:

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

Utilização

O {geocodebr} possui três funções principais para geolocalização de dados:

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:

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.
O segundo passo é usar a função geocode() para encontrar as coordenadas geográficas dos endereços de input.

library(geocodebr)
library(sf)
#> Linking to GEOS 3.10.2, GDAL 3.4.1, PROJ 8.2.1; sf_use_s2() is TRUE

# 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
)
#> Warning: Foram encontrados 1 casos de empate. Estes casos foram marcados com valor
#> `TRUE` na coluna 'empate', e podem ser inspecionados na coluna
#> 'endereco_encontrado'. Alternativamente, use `resolver_empates = TRUE` para que
#> o pacote lide com os empates automaticamente. Ver documentação da função.

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
)

Cache de dados

Como comentado anteriormente, os dados do CNEFE são baixados na primeira vez que a geocode() é executada. Esses dados ficam salvos no cache do pacote e não precisam ser baixados novamente. O pacote inclui algumas funções que ajudam a gerenciar o cache:

listar_pasta_cache() - retorna o endereço do cache na sua máquina, onde os dados do CNEFE estão salvos;
definir_pasta_cache() - define uma pasta personalizada para ser usada como cache. Essa configuração é persistente entre diferentes sessões do R;
listar_dados_cache() - lista todos os arquivos armazenados no cache;
deletar_pasta_cache() - exclui a pasta de cache, bem como todos os arquivos que estavam armazenados dentro dela.

Após rodar o código desta vignette, é provável que o seu cache esteja configurado como a seguir: