Introdução ao geocodebr

The hardware and bandwidth for this mirror is donated by METANET, the Webhosting and Full Service-Cloud Provider.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]metanet.ch.

2025-02-17

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, 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

A principal função do pacote é a geocode(), que recebe uma tabela (data.frame) de endereços como entrada e retorna a mesma tabela geolocalizada como saída. Para demonstrar o pacote, 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:

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"
)

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. No total, esses dados somam cerca de 3 GB, o que pode fazer com que a primeira execução da função demore, já que é necessário baixar os dados para a sua máquina. Esses dados, no entanto, são salvos de forma persistente, logo eles são baixados uma única vez.

# geolicalização
ends_geo <- geocode(
  enderecos = ends, 
  campos_endereco = campos, 
  resultado_completo = FALSE,
  resolver_empates = TRUE,
  resultado_sf = FALSE,
  verboso = FALSE
  )
#> The tzdb package is not installed. Timezones will not be available to Arrow compute functions.

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 tipo_resultado
#>             <char>     <int> <char>      <num>     <num>         <char>
#> 1:     Nova Iguacu   3303500     RJ -22.695496 -43.47118           dn01
#> 2: Duque de Caxias   3301702     RJ -22.779174 -43.31134           dn01
#> 3:  Angra dos Reis   3300100     RJ -22.978837 -44.20848           dl01
#> 4:  Rio de Janeiro   3304557     RJ -22.868992 -43.51150           dl01
#> 5:     Mangaratiba   3302601     RJ -22.929864 -43.97214           dn01
#> 6:      Rio Branco   1200401     AC  -9.963436 -67.83559           dn03
#>      precisao
#>        <char>
#> 1:     numero
#> 2:     numero
#> 3: logradouro
#> 4: logradouro
#> 5:     numero
#> 6:     numero
#>                                                            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

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.

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

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, padrão adotado pelo IBGE em todo o Brasil. Cada par de coordenadas encontrado pode ser classificado conforme o seu grau de precisão (coluna precisao) e os campos do endereço utilizados para encontrá-lo (tipo_resultado). A seção a seguir apresenta mais informações sobre essas colunas.

Grau de precisão dos resultados

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. 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 cada um dos 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.

A coluna precisao se refere ao nível de agregação das coordenadas do CNEFE utilizadas pela geocode(). A função sempre retorna o resultado de maior precisão possível - ou seja, ela só vai procurar endereços com precisão "numero_aproximado" (ver a seguir) caso não tenha encontrado correspondência de precisão "numero". As coordenadas calculadas podem ser classificadas em seis diferentes categorias de precisão:

"numero" - calculadas a partir de endereços que compartilham o mesmo logradouro e número;
"numero_aproximado" - calculadas a partir de endereços que compartilham o mesmo logradouro, mas número de input não encontra correspondência exata no CNEFE e sua localização é calculada a partir de uma interpolação espacial;
"logradouro" - calculadas a partir de endereços que compartilham o mesmo logradouro (número de input está ausente ou é S/N);
"cep" - calculadas a partir de endereços que compartilham o mesmo CEP;
"localidade" - calculadas a partir de endereços que compartilham a mesma localidade;
"municipio" - calculadas a partir de endereços que compartilham o mesmo município.

A coluna tipo_resultado fornece informações mais detalhadas sobre os campos de endereço utilizados no cálculo das coordenadas de cada endereço de entrada. Cada categoria é nomeada a partir de um código de quatro caracteres:

o primeiro, sempre d ou p, determina se a correspondência foi feita de forma determinística (d) ou probabilística (p) - a segunda opção ainda não foi implementada no pacote, mas é planejada em versões futuras;
o segundo faz menção à categoria de precisao na qual o resultado foi classificado (n para "numero", a para "numero_aproximado", l para "logradouro", c para "cep", b para "localidade" e m para "municipio");
o terceiro e o quarto designam a classificação de cada categoria dentro de seu grupo - via de regra, quanto menor o número formado por esses caracteres, mais precisa são as coordenadas calculadas.

As categorias de tipo_resultado são listadas abaixo, junto às categorias de precisao a qual elas estão associadas:

precisao "numero"
- dn01 - logradouro, numero, cep e localidade
- dn02 - logradouro, numero e cep
- dn03 - logradouro, numero e localidade
- dn04 - 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"
- da01 - logradouro, numero, cep e localidade
- da02 - logradouro, numero e cep
- da03 - logradouro, numero e localidade
- da04 - logradouro e numero
- pa01 - logradouro, numero, cep e localidade
- pa02 - logradouro, numero e cep
- pa03 - logradouro, numero e localidade
- pa04 - logradouro e numero
precisao "logradouro" (quando o número de entrada está faltando ‘S/N’)
- dl01 - logradouro, cep e localidade
- dl02 - logradouro e cep
- dl03 - logradouro e localidade
- dl04 - logradouro
- pl01 - logradouro, cep e localidade
- pl02 - logradouro e cep
- pl03 - logradouro e localidade
- pl04 - logradouro
precisao "cep"
- dc01 - municipio, cep, localidade
- dc02 - municipio, cep
precisao "localidade"
- db01 - municipio, localidade
precisao "municipio"
- dm01 - municipio

Endereços não encontrados são retornados com latitude, longitude, precisão e tipo de resultado NA.

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

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:

listar_pasta_cache()
#> [1] "C:/Users/r1701707/AppData/Local/R/cache/R/geocodebr/data_release_v0.2.0"

listar_dados_cache()
#> [1] "C:/Users/r1701707/AppData/Local/R/cache/R/geocodebr/data_release_v0.2.0/municipio.parquet"                                 
#> [2] "C:/Users/r1701707/AppData/Local/R/cache/R/geocodebr/data_release_v0.2.0/municipio_cep.parquet"                             
#> [3] "C:/Users/r1701707/AppData/Local/R/cache/R/geocodebr/data_release_v0.2.0/municipio_cep_localidade.parquet"                  
#> [4] "C:/Users/r1701707/AppData/Local/R/cache/R/geocodebr/data_release_v0.2.0/municipio_localidade.parquet"                      
#> [5] "C:/Users/r1701707/AppData/Local/R/cache/R/geocodebr/data_release_v0.2.0/municipio_logradouro_cep_localidade.parquet"       
#> [6] "C:/Users/r1701707/AppData/Local/R/cache/R/geocodebr/data_release_v0.2.0/municipio_logradouro_localidade.parquet"           
#> [7] "C:/Users/r1701707/AppData/Local/R/cache/R/geocodebr/data_release_v0.2.0/municipio_logradouro_numero_cep_localidade.parquet"
#> [8] "C:/Users/r1701707/AppData/Local/R/cache/R/geocodebr/data_release_v0.2.0/municipio_logradouro_numero_localidade.parquet"

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.