https://github.com/ipeagit/geocodebr
Geolocalização de Endereços Brasileiros (Geocoding Brazilian Addresses)
https://github.com/ipeagit/geocodebr
brazil cnefe geocoding r
Last synced: 14 days ago
JSON representation
Geolocalização de Endereços Brasileiros (Geocoding Brazilian Addresses)
- Host: GitHub
- URL: https://github.com/ipeagit/geocodebr
- Owner: ipeaGIT
- License: other
- Created: 2024-09-16T22:48:07.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2026-01-23T21:24:46.000Z (18 days ago)
- Last Synced: 2026-01-24T07:51:08.308Z (18 days ago)
- Topics: brazil, cnefe, geocoding, r
- Language: R
- Homepage: https://ipeagit.github.io/geocodebr/
- Size: 11.9 MB
- Stars: 65
- Watchers: 3
- Forks: 4
- Open Issues: 7
-
Metadata Files:
- Readme: README.Rmd
- Changelog: NEWS.md
- License: LICENSE
- Codemeta: codemeta.json
Awesome Lists containing this project
README
---
output: github_document
---
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# geocodebr: Geolocalização de Endereços Brasileiros 
[](https://CRAN.R-project.org/package=geocodebr)
[](https://CRAN.R-project.org/package=geocodebr)
[](https://github.com/ipeaGIT/geocodebr/actions)
[](https://app.codecov.io/gh/ipeaGIT/geocodebr?branch=main)
[](https://lifecycle.r-lib.org/articles/stages.html)
O **{geocodebr}** é um pacote computacional para geolicalização de endereços Brasileiros. O pacote oferece uma maneira simples e eficiente de geolocalizar
dados sem limite de número de consultas. O pacote é baseado em conjuntos de dados espaciais abertos de endereços brasileiros, utilizando como fonte principal o Cadastro Nacional de Endereços para Fins Estatísticos (CNEFE). O CNEFE é
[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). Atualmente, o pacote está disponível apenas em R.
## Instalação
A última versão estável pode ser baixada do CRAN com o comando:
```r
# from CRAN
install.packages("geocodebr")
```
Caso prefira, a versão em desenvolvimento:
```r
# 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, eval=TRUE, message=FALSE, warning=FALSE}
library(geocodebr)
library(sf)
# carregando uma amostra de dados
input_df <- read.csv(system.file("extdata/small_sample.csv", package = "geocodebr"))
# Primeiro passo: indicar 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 = TRUE,
resultado_sf = TRUE,
verboso = FALSE
)
```
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. Os resultados trazem ainda uma estimativa da
incerteza da localização encontrada 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. A função pode ser útil, por exemplo, para identificar endereços próximos a pontos
de interesse, como escolas, hospitais, ou locais de acidentes. Aqui um exemplo de
como usar a função:
```{r, eval=TRUE}
# 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
)
```
Mais detalhes na [**vignette "geocode reverso"**](https://ipeagit.github.io/geocodebr/articles/geocode_reverso.html).
### 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 e suas coordenadas espaciais.
```{r, eval=TRUE}
# amostra de CEPs
ceps <- c("70390-025", "20071-001")
df_ceps <- geocodebr::busca_por_cep(
cep = ceps,
resultado_sf = TRUE,
verboso = FALSE
)
```
## Nota 
Os dados originais do CNEFE são coletados pelo Instituto Brasileiro de Geografia e Estatística (IBGE). O **{geocodebr}** foi desenvolvido por uma equipe do Instituto de Pesquisa Econômica Aplicada (Ipea), e conta com apoio do Instituto Todos pela Saúde (ITpS).
## Instituições utilizando o {geocodebr}
Além de diversos pesquisadores e empresas que utilizam o {geocodebr}, o pacote também tem sido utilizado por algumas instituições públicas no planejamento e avaliação de políticas públicas. Entre elas:
- Instituto Brasileiro de Geografia e Estatistica (IBGE)
- Banco Central do Brasil (BCB)
- Ministério do Desenvolvimento Social e Combate à Fome (MDS)
## Projetos relacionados
Existem diversos pacotes de geolocalização disponíveis, muitos dos quais podem
ser utilizados em R (listados abaixo). A maioria dessas alternativas depende de softwares e conjuntos de dados comerciais, geralmente impondo limites de número
de consultas gratuitas. Em contraste, as principais vantagens do **{geocodebr}**
são que o pacote: (a) é completamente gratuito, permitindo consultas ilimitadas
sem nenhum custo; (b) opera com alta velocidade e escalabilidade eficiente, permitindo geocodificar milhões de endereços em apenas alguns minutos, sem a necessidade de infraestrutura computacional avançada ou de alto desempenho.
- [{arcgisgeocode}](https://cran.r-project.org/package=arcgisgeocode) and [{arcgeocoder}](https://cran.r-project.org/package=arcgeocoder): utiliza serviço de geocode do ArcGIS
- [{nominatimlite}](https://cran.r-project.org/package=nominatimlite): baseado dados do OSM
- [{photon}](https://cran.r-project.org/package=photon): baseado dados do OSM
- [{tidygeocoder}](https://cran.r-project.org/package=tidygeocoder): API para diversos servicos de geolocalização
- [{googleway}](https://cran.r-project.org/package=googleway) and [{mapsapi}](https://cran.r-project.org/package=mapsapi): interface para API do Google Maps