Geolocaliza endereços no Brasil — geocode • geocodebr

Geocodifica endereços brasileiros com base nos dados do CNEFE. Os endereços de input devem ser passados como um data.frame, no qual cada coluna descreve um campo do endereço (logradouro, número, cep, etc). O resuldos dos endereços geolocalizados podem seguir diferentes níveis de precisão. Consulte abaixo a seção "Detalhes" para mais informações. As coordenadas de output utilizam o sistema de referência geodésico "SIRGAS2000", CRS(4674).

Usage

geocode(
  enderecos,
  campos_endereco = definir_campos(),
  resultado_completo = FALSE,
  resolver_empates = FALSE,
  resultado_sf = FALSE,
  verboso = TRUE,
  cache = TRUE,
  n_cores = 1
)

Arguments

enderecos: Um data.frame. Os endereços a serem geolocalizados. Cada coluna deve representar um campo do endereço.
campos_endereco: Um vetor de caracteres. A correspondência entre cada campo de endereço e o nome da coluna que o descreve na tabela enderecos. A função definir_campos() auxilia na criação deste vetor e realiza algumas verificações nos dados de entrada. Campos de endereço passados como NULL serão ignorados, e a função deve receber pelo menos um campo não nulo, além dos campos "estado" e "municipio", que são obrigatórios. Note que o campo "localidade" é equivalente a 'bairro'.
resultado_completo: Lógico. Indica se o output deve incluir colunas adicionais, como o endereço encontrado de referência. Por padrão, é FALSE.
resolver_empates: Lógico. Alguns resultados da geolocalização podem indicar diferentes coordenadas possíveis (e.g. duas ruas diferentes com o mesmo nome em uma mesma cidade). Esses casos são trados como 'empate' e o parâmetro resolver_empates indica se a função deve resolver esses empates automaticamente. Por padrão, é FALSE, e a função retorna apenas o caso mais provável.
resultado_sf: Lógico. Indica se o resultado deve ser um objeto espacial da classe sf. Por padrão, é FALSE, e o resultado é um data.frame com as colunas lat e lon. adicionais, como o endereço encontrado de referência. Por padrão, é FALSE.
verboso: Um valor lógico. Indica se barras de progresso e mensagens devem ser exibidas durante o download dos dados do CNEFE e a geocodificação dos endereços. O padrão é TRUE.
cache: Um valor lógico. Indica se os dados do CNEFE devem ser salvos ou lidos do cache, reduzindo o tempo de processamento em chamadas futuras. O padrão é TRUE. Quando FALSE, os dados do CNEFE são baixados para um diretório temporário.
n_cores: Um número. O número de núcleos de CPU a serem utilizados no processamento dos dados. O padrão é 1.

Value

Retorna o data.frame de input enderecos adicionado das colunas de latitude (lat) e longitude (lon), bem como as colunas (precisao e tipo_resultado) que indicam o nível de precisão e o tipo de resultado. Alternativamente, o resultado pode ser um objeto sf.

Details

Precisão dos resultados:

Os resultados do geocodebr são classificados em seis amplas categorias de precisao:

"numero"
"numero_aproximado"
"logradouro"
"cep"
"localidade"
"municipio"

Cada nível de precisão pode ser desagregado em tipos de correspondência mais refinados.

Tipos de resultados

A coluna tipo_resultado fornece informações mais detalhadas sobre como exatamente cada endereço de entrada foi encontrado no CNEFE. Em cada categoria, o geocodebr calcula a média da latitude e longitude dos endereços incluídos no CNEFE que correspondem ao endereço de entrada, com base em combinações de diferentes campos. No caso mais rigoroso, por exemplo, a função encontra uma correspondência determinística para todos os campos de um dado endereço ("estado", "municipio", "logradouro", "numero", "cep", "localidade"). Pense, por exemplo, em um prédio com vários apartamentos que correspondem ao mesmo endereço de rua e número. Nesse caso, as coordenadas dos apartamentos podem diferir ligeiramente, e o geocodebr calcula a média dessas coordenadas. Em um caso menos rigoroso, no qual apenas os campos ("estado", "municipio", "logradouro", "localidade") são encontrados, o geocodebr calcula as coordenadas médias de todos os endereços no CNEFE ao longo daquela rua e que se encontram na mesma localidade/bairro. Assim, as coordenadas de resultado tendem a ser o ponto médio do trecho daquela rua que passa dentro daquela localidade/bairro.

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 caracter, 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", r para "logradouro", c para "cep", b para "localidade" e m para "municipio");
o terceiro e o quarto caracteres 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.

Examples

library(geocodebr)

# ler amostra de dados
data_path <- system.file("extdata/small_sample.csv", package = "geocodebr")
input_df <- read.csv(data_path)

fields <- geocodebr::definir_campos(
  logradouro = "nm_logradouro",
  numero = "Numero",
  cep = "Cep",
  localidade = "Bairro",
  municipio = "nm_municipio",
  estado = "nm_uf"
)

df <- geocodebr::geocode(
  enderecos = input_df,
  campos_endereco = fields,
  resolver_empates = TRUE,
  verboso = FALSE
  )

head(df)
#>       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