Geocode

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

A principal função do pacote {geocodebr} é a geocode(), que recebe uma tabela (data.frame) de endereços como entrada e retorna a mesma tabela geolocalizada como saída. Para demonstrar essa função, utilizamos no exemplo abaixo pequeno conjunto de dados que contém endereços com problemas comuns, como informações ausentes e campos digitados incorretamente.

A geolocalização desses dados com {geocodebr} 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. No exemplo abaixo, nós indicamos que coluna que contém a informação de logradouro se chama "nm_logradouro", que a coluna de número se chama "Numero", etc.

obs. Note que as colunas indicando o "estado" e "município" são obrigatórias.

library(geocodebr)

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

# definição dos campos de endereço
campos <- definir_campos(
  estado = "nm_uf",
  municipio = "nm_municipio",
  logradouro = "nm_logradouro",
  numero = "Numero",
  cep = "Cep",
  localidade = "Bairro"
)

2. O segundo passo é usar a função geocode() para encontrar as coordenadas geográficas dos dados de input.

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 1.2 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. Mais informações sobre o cache de dados aqui.

# geolicalização
ends_geo <- geocode(
  enderecos = ends, 
  campos_endereco = campos, 
  resultado_completo = FALSE,
  resolver_empates = TRUE,
  h3_res = 9,
  resultado_sf = FALSE,
  verboso = FALSE
  )

head(ends_geo)
#>       id            nm_logradouro Numero       Cep               Bairro
#>    <int>                   <char>  <int>    <char>               <char>
#> 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           Estacao Experimental
#>       nm_municipio code_muni  nm_uf        lat       lon   precisao
#>             <char>     <int> <char>      <num>     <num>     <char>
#> 1:     Nova Iguacu   3303500     RJ -22.695509 -43.47116     numero
#> 2: Duque de Caxias   3301702     RJ -22.779175 -43.31132     numero
#> 3:  Angra dos Reis   3300100     RJ -22.978800 -44.20847 logradouro
#> 4:  Rio de Janeiro   3304557     RJ -22.869117 -43.51140 logradouro
#> 5:     Mangaratiba   3302601     RJ -22.929865 -43.97214     numero
#> 6:      Rio Branco   1200401     AC  -9.963438 -67.83559     numero
#>    tipo_resultado desvio_metros
#>            <char>         <int>
#> 1:           dn01             9
#> 2:           dn01             6
#> 3:           dl01            59
#> 4:           dl01           300
#> 5:           dn01             6
#> 6:           dn03             6
#>                                                            endereco_encontrado
#>                                                                         <char>
#> 1:      RUA MARIA LUCIA PACIFICO, 17 - SANTA RITA, NOVA IGUACU - RJ, 26042-730
#> 2:       RUA LEOPOLDINA TOME, 46 - CENTENARIO, DUQUE DE CAXIAS - RJ, 25030-050
#> 3:               RUA DONA JUDITE - CAPUTERA II, ANGRA DOS REIS - RJ, 23915-700
#> 4:           RUA ALEXANDRE AMARAL - SANTISSIMO, RIO DE JANEIRO - RJ, 23098-120
#> 5:                  AVENIDA E, 300 - PRAIA GRANDE, MANGARATIBA - RJ, 23860-000
#> 6: RUA PRINCESA ISABEL, 263 - ESTACAO EXPERIMENTAL, RIO BRANCO - AC, 69921-026
#>              h3_09
#>             <char>
#> 1: 89a8a39850fffff
#> 2: 89a8a06c55bffff
#> 3: 89a8a1c190fffff
#> 4: 89a8a066c47ffff
#> 5: 89a8a026c77ffff
#> 6: 898b5131e0fffff

Por padrão, a tabela de output é igual à tabela de input do usuário acrescida de colunas com a latitude e longitude encontradas, bem como de colunas indicando o nível de precisão dos resultados e o endereço encontrado. Quando resultado_completo = TRUE, o output é acrescido de algumas colunas extras discriminando separadamente cada componente do endereço que teria sido encontrado.

Cabe também destacar aqui outros três argumentos da função geocode():

• h3_res : que permite o usuário inserir uma coluna no output indicando o id da célula H3 na resolução espacial desejada. Detalhes sobre as resoluções disponíveis em \code{;
• resolver_empates: serve para indicar se o usuário quer que a função resolva automaticamente casos de empate, i.e. casos que o endereço de input do usuário pode se referir a diferentes localidades na cidade (e.g. logradouros diferentes com mesmo nome mas em bairros distintos). Quando TRUE, a função resolve os empates selecioando os endereços com maior número de visitas do CNEFE. Quando FALSE, a função retorna todos os resultados indicando os casos empatados na coluna ‘empate’ para que o usuário possa inspecionar cada caso coluna ‘endereco_encontrado’.
• resultado_sf: quando TRUE, o output é retornado como um objeto espacial de classe sf simple feature.

As coordendas espaciais do resultado usam o sistema de referência SIRGAS2000 (EPSG 4674.), padrão adotado pelo IBGE em todo o Brasil.

Processo de matching de endereços

As coordenadas incluídas no resultado da geocode() são calculadas a partir da média das coordenadas dos endereços do CNEFE que correspondem a cada um dos endereços de input. Esse cálculo é feito em duas etapas, e retorna o ponto médio dos 95% pontos mais próximos entre si, evitando eventual distorção por devido a poucos pontos muito isolados.

A correspondência entre os endereços de entrada e os do CNEFE pode ser feita com base em diferentes combinações de campos, impactando, assim, na precisão do resultado retornado. No caso mais rigoroso, a função encontra uma correspondência determinística para todos os campos do endereço (estado, município, logradouro, número, CEP e localidade). Pense, por exemplo, em um prédio com vários apartamentos, cuja única variação no endereço se dá a nível de apartamento: o resultado, nesse caso, é a média das coordenadas dos apartamentos, que podem diferir ligeiramente.

Em um caso menos rigoroso, no qual são encontradas correspondências apenas para os campos de estado, município, logradouro e localidade, a função calcula as coordenadas médias de todos os endereços do CNEFE que se encontram na mesma rua e na mesma localidade. O resultado, portanto, é agregado a nível de rua, tendendo para a extremidade do logradouro com maior concentração de endereços.

Grau de precisão dos resultados

A precisão dos resultados do {geocodebr} são apresentadas em 3 colunas, precisao, tipo_resultado e desvio_metros, explicadas abaixo.