---
title: "Geocode reverso"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
code-annotations: hover
urlcolor: blue
vignette: >
  %\VignetteIndexEntry{Geocode reverso}
  %\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 reversa: de coordenadas espaciais para endereços

A função `geocode_reverso()` permite fazer geolocalização reversa, isto é,  a partir de um conjunto de coordenadas geográficas, encontrar os endereços correspondentes ou próximos. Essa funcionalidade pode ser útil, por exemplo, para identificar endereços próximos a pontos de interesse, como escolas, hospitais, ou locais de acidentes.

A função recebe como *input* um objeto espacial `sf` com geometria do tipo `POINT`. O resultado é um *data frame* com o endereço encontrado mais próximo de cada ponto de *input*, onde a coluna `"distancia_metros"` indica a distância entre coordenadas originais e os endereços encontrados.


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

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

pontos <- pontos[1:20,]

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

head(df_enderecos)
```

Por padrão, a função busca pelo endereço mais próximo num raio aproximado de 1000 metros. No entanto,  o usuário pode ajustar esse valor usando o parâmetro `dist_max` para definir a distância máxima (em metros) de busca. Se um ponto de *input* não tiver nenhum endereço próximo dentro do raio de busca, o ponto não é incluído no *output*.

**Nota:** A função `geocode_reverso()` 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](https://ipeagit.github.io/geocodebr/articles/geocodebr.html#cache-de-dados).