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.

Geocode

2025-05-07

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"
)
  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. 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. 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,
  resultado_sf = FALSE,
  verboso = FALSE
  )

head(ends_geo)

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 (EPSG 4674.), 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.

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.