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-10-08

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

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():

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.

Precisão

A coluna precisao se refere ao nível de agregação das coordenadas do CNEFE utilizadas no processo de geolicalização. A função geocode() 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.

Tipos de resultados

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.

Desvio em metros

A coluna desvio_metros apresenta uma forma intuitiva e prática de saber o grau de incerteza do resultado encontrado. Essa coluna informa que pelo menos 95% de todos os pontos do CNEFE que possuem corrêspondência com o endereço de input estão num raio de x metros da localização encontrada.

Um desvio de 30 metros, por exemplo, tende a representar um resultado muito confiável. A depender de como o dado geolocalizado será utilizado, até mesmos resultados com um desvio_metros de até 500 ou 900 metros podem ser ser aceitáveis.

A coluna desvio_metros pode ser particularmente útil para decidir por exemplo se um resultado encontrado com a precisao de CEP deveria ser aceitável. Muitas cidades do Brasil possuem um CEP único, o que tende a gerar resultados com altíssimo grau de incerteza. Em várias cidades, no entanto, um CEP pode ser circunscrito a uma área muito pequena e as vezes até um único edifício. Nesses casos, o valor do desvio_metros tende a ser bem pequeno.

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.