The hardware and bandwidth for this mirror is donated by dogado GmbH, the Webhosting and Full Service-Cloud Provider. Check out our Wordpress Tutorial.
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[@]dogado.de.

Introdução ao geocodebr

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:

  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"
)
  1. 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():

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:

  1. "numero" - calculadas a partir de endereços que compartilham o mesmo logradouro e número;
  2. "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;
  3. "logradouro" - calculadas a partir de endereços que compartilham o mesmo logradouro (número de input está ausente ou é S/N);
  4. "cep" - calculadas a partir de endereços que compartilham o mesmo CEP;
  5. "localidade" - calculadas a partir de endereços que compartilham a mesma localidade;
  6. "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:

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

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:

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.
Health stats visible at Monitor.