Skip to contents

Geolocalização com geocodebr (PORT)

2025-01-12

Source: vignettes/geocoding_pt.Rmd
geocoding_pt.Rmd

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 setup_address_fields() 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::setup_address_fields(
  logradouro = "nm_logradouro",
  numero = "Numero",
  cep = "Cep",
  bairro = "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(
  addresses_table = input_df,
  address_fields = fields,
  n_cores = 1,
  progress = FALSE
  )

head(df)
#>   id            nm_logradouro Numero       Cep               Bairro
#> 1  1 RUA MARIA LUCIA PACIFICO     17 26042-730           SANTA RITA
#> 2  2      RUA LEOPOLDINA TOME     46 25030-050           CENTENARIO
#> 3  3          RUA DONA JUDITE      0 23915-700          CAPUTERA II
#> 4  4     RUA ALEXANDRE AMARAL      0 23098-120           SANTISSIMO
#> 5  5                AVENIDA E    300 23860-000         PRAIA GRANDE
#> 6  6      RUA PRINCESA ISABEL    263 69921-026 ESTACAO EXPERIMENTAL
#>      nm_municipio code_muni          nm_uf       lon        lat match_type
#> 1     NOVA IGUACU   3303500 RIO DE JANEIRO -43.47118 -22.695496       en01
#> 2 DUQUE DE CAXIAS   3301702 RIO DE JANEIRO -43.31134 -22.779173       en01
#> 3  ANGRA DOS REIS   3300100 RIO DE JANEIRO -44.20848 -22.978837       er01
#> 4  RIO DE JANEIRO   3304557 RIO DE JANEIRO -43.51150 -22.868992       er01
#> 5     MANGARATIBA   3302601 RIO DE JANEIRO -43.97214 -22.929864       en01
#> 6      RIO BRANCO   1200401           ACRE -67.83559  -9.963436       en01
#>   precision
#> 1    number
#> 2    number
#> 3    street
#> 4    street
#> 5    number
#> 6    number

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: precision e match_type. Mais informações abaixo.

Categorias de Precisão: precision

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

  • “numero”
  • “numero_interpolado”
  • “rua”
  • “cep”
  • “bairro”
  • “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: match_type

A coluna match_type 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 no mesmo bairro. Assim, as coordenadas de resultado tendem a ser o ponto médio do trecho daquela rua que passa dentro daquele bairro.

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

  • precision: “numero”
    • match_type:
      • en01: logradouro, numero, cep e bairro
      • en02: logradouro, numero e cep
      • en03: logradouro, numero e bairro
      • en04: logradouro e numero
      • pn01: logradouro, numero, cep e bairro
      • pn02: logradouro, numero e cep
      • pn03: logradouro, numero e bairro
      • pn04: logradouro e numero
  • precision: “numero_interpolado”
    • match_type:
      • ei01: logradouro, numero, cep e bairro
      • ei02: logradouro, numero e cep
      • ei03: logradouro, numero e bairro
      • ei04: logradouro e numero
      • pi01: logradouro, numero, cep e bairro
      • pi02: logradouro, numero e cep
      • pi03: logradouro, numero e bairro
      • pi04: logradouro e numero
  • precision: “rua” (quando o número de entrada está faltando ‘S/N’)
    • match_type:
      • er01: logradouro, cep e bairro
      • er02: logradouro e cep
      • er03: logradouro e bairro
      • er04: logradouro
      • pr01: logradouro, cep e bairro
      • pr02: logradouro e cep
      • pr03: logradouro e bairro
      • pr04: logradouro
  • precision: “cep”
    • match_type:
      • ec01: municipio, cep, localidade
      • ec02: municipio, cep
  • precision: “bairro”
    • match_type:
      • eb01: municipio, localidade
  • precision: “municipio”
    • match_type:
      • em01: municipio

Nota: As categorias de match_type 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 match_type que usam correspondência probabilística ainda não estão implementados no {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:

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