# Geocode

#### 2025-07-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"
    )

2. 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
      )
    #> Warning in max(contagem_cnefe, na.rm = TRUE): no non-missing arguments to max;
    #> returning -Inf

    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.779173 -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
    #>    empate
    #>    <lgcl>
    #> 1:  FALSE
    #> 2:  FALSE
    #> 3:  FALSE
    #> 4:  FALSE
    #> 5:  FALSE
    #> 6:  FALSE

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

- `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. 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:

- o primeiro, sempre `d` ou `p`, determina se a correspondência foi feita de forma determinística (`d`) ou probabilística (`p`);
- o segundo faz menção à categoria de `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"`);
- o terceiro e o quarto 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`.