---
title: "Introdução ao geocodebr"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
code-annotations: hover
urlcolor: blue
vignette: >
  %\VignetteIndexEntry{Introdução ao geocodebr}
  %\VignetteEngine{knitr::rmarkdown}
  \usepackage[utf8]{inputenc}
---
  
```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  eval = identical(tolower(Sys.getenv("NOT_CRAN")), "true"),
  out.width = "100%"
)

# CRAN OMP THREAD LIMIT to avoid CRAN NOTE
Sys.setenv(OMP_THREAD_LIMIT = 2)
```

Geolocalização refere-se ao ato de encontrar um ponto no espaço, geralmente
representado por um par de coordenadas, a partir de um determinado endereço. O
**geocodebr** permite geolocalizar endereços brasileiros de forma simples e
eficiente e sem limite de número de consultas, a partir de dados públicos de 
endereços do Brasil. A principal base de referência é o Cadastro Nacional de 
Endereços para Fins Estatísticos (CNEFE), um conjunto de dados coletado e
[publicado](https://www.ibge.gov.br/estatisticas/sociais/populacao/38734-cadastro-nacional-de-enderecos-para-fins-estatisticos.html) pelo Instituto Brasileiro de Geografia e Estatística 
(IBGE) que contém os endereços de mais de 110 milhões de domicílios e 
estabelecimentos do país.


## Instalação

A versão estável do pacote pode ser baixada do CRAN com o comando a seguir:
  
```{r, eval = FALSE}
install.packages("geocodebr")
```

Caso prefira, a versão em desenvolvimento:
  
```{r, eval = FALSE}
# install.packages("remotes")
remotes::install_github("ipeaGIT/geocodebr")
```



## Utilização

O **{geocodebr}** possui três funções principais para geolocalização de dados:
  
1. `geocode()`
2. `geocode_reverso()`
3. `busca_por_cep()`


### 1. Geolocalização: de endereços para coordenadas espaciais

Uma vez que você possui uma tabela de dados (`data.frame`) com endereços no Brasil, a geolocalização desses dados 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.
2. O segundo passo é usar a função `geocode()` para encontrar as coordenadas geográficas dos endereços de input.

```{r}
library(geocodebr)
library(sf)

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

# Primeiro passo: inidicar o nome das colunas com cada campo dos enderecos
campos <- geocodebr::definir_campos(
  logradouro = "nm_logradouro",
  numero = "Numero",
  cep = "Cep",
  localidade = "Bairro",
  municipio = "nm_municipio",
  estado = "nm_uf"
)

# Segundo passo: geolocalizar
df <- geocodebr::geocode(
  enderecos = input_df,
  campos_endereco = campos,
  resultado_completo = FALSE,
  resolver_empates = FALSE,
  h3_res = NULL,
  resultado_sf = FALSE,
  verboso = FALSE,
  cache = TRUE,
  n_cores = 1
)

```

**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.4 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.
Ver abaixo mais informações sobre o cache de dados.

Os resultados do **{geocodebr}** são classificados em seis categorias gerais de `precisao`, dependendo do nível de exatidão com que cada endereço de input foi encontrado nos dados do CNEFE. s resultados trazem ainda uma estimativa da 
incerteza da localização encontrado como um `desvio_metros`. Para mais 
informações, consulte a documentação da função ou a [**vignette "geocode"**](https://ipeagit.github.io/geocodebr/articles/geocode.html).


### 2. Geolocalização reversa: de coordenadas espaciais para endereços

A função `geocode_reverso()`, por sua vez, permite a geolocalização reversa, ou seja, a busca de endereços próximos a um conjunto de coordenadas geográficas. Mais detalhes na [**vignette "geocode"**](https://ipeagit.github.io/geocodebr/articles/geocode_reverso.html).

```{r}
# amostra de pontos espaciais
pontos <- readRDS(
  system.file("extdata/pontos.rds", package = "geocodebr")
)

# seleciona somente os primeiros 20 pontos
pontos <- pontos[1:20,]

# geocode reverso
df_enderecos <- geocodebr::geocode_reverso(
  pontos = pontos,
  dist_max = 1000,
  verboso = FALSE,
  n_cores = 1
)

```


### 3. Busca por CEPs

Por fim, a função `busca_por_cep()` permite fazer consultas de CEPs para encontrar endereços associados a cada CEP. A função recebe um vetor de CEPs e retorna um `data.frame` com os endereços e as coordenadas geográficas de cada CEP. O parâmetro
`h3_res` pode ser utilizado para incluir no output o id das células H3 na resolução
espacial desejada.

```{r}
# amostra de CEPs
ceps <- c("70390-025", "20071-001")

df_ceps <- geocodebr::busca_por_cep(
  cep = ceps,
  h3_res = 9,
  resultado_sf = FALSE,
  verboso = FALSE
)

```


## Cache de dados

Como comentado anteriormente, os dados do CNEFE são baixados na primeira vez que
a `geocode()` é executada. Esses dados ficam salvos no *cache* do pacote e não
precisam ser baixados novamente. O pacote inclui algumas funções que ajudam a
gerenciar o *cache*:
  
- `listar_pasta_cache()` - retorna o endereço do *cache* na sua máquina, onde os
dados do CNEFE estão salvos;
- `definir_pasta_cache()` - define uma pasta personalizada para ser usada como
*cache*. Essa configuração é persistente entre diferentes sessões do R;
- `listar_dados_cache()` - lista todos os arquivos armazenados no *cache*;
- `deletar_pasta_cache()` - exclui a pasta de *cache*, bem como todos os
arquivos que estavam armazenados dentro dela.

Após rodar o código desta *vignette*, é provável que o seu *cache* esteja
configurado como a seguir:
  
```{r}
geocodebr::listar_pasta_cache()

geocodebr::listar_dados_cache()
```