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.
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:
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"
)
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()
:
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.
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.
A precisão dos resultados do {geocodebr} são
apresentadas em 3 colunas, precisao
,
tipo_resultado
e desvio_metros
, explicadas
abaixo.
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:
"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:
d
ou p
, determina se a
correspondência foi feita de forma determinística (d
) ou
probabilística (p
);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"
);As categorias de tipo_resultado
são listadas abaixo,
junto às categorias de precisao
a qual elas estão
associadas:
"numero"
dn01
- logradouro, numero, cep e localidadedn02
- logradouro, numero e cepdn03
- logradouro, numero e localidadedn04
- logradouro e numeropn01
- logradouro, numero, cep e localidadepn02
- logradouro, numero e ceppn03
- logradouro, numero e localidadepn04
- logradouro e numero"numero_aproximado"
da01
- logradouro, numero, cep e localidadeda02
- logradouro, numero e cepda03
- logradouro, numero e localidadeda04
- logradouro e numeropa01
- logradouro, numero, cep e localidadepa02
- logradouro, numero e ceppa03
- logradouro, numero e localidadepa04
- logradouro e numero"logradouro"
(quando o número de entrada está
faltando ‘S/N’)
dl01
- logradouro, cep e localidadedl02
- logradouro e cepdl03
- logradouro e localidadedl04
- logradouropl01
- logradouro, cep e localidadepl02
- logradouro e ceppl03
- logradouro e localidadepl04
- logradouro"cep"
dc01
- municipio, cep, localidadedc02
- municipio, cep"localidade"
db01
- municipio, localidade"municipio"
dm01
- municipioEndereços não encontrados são retornados com latitude, longitude,
precisão e tipo de resultado NA
.
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.