Learn R Programming

geocodebr: Geolocalização de Endereços Brasileiros

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

# from CRAN
install.packages("geocodebr")

Caso prefira, a versão em desenvolvimento:

# 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.

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”.

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:

# 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”.

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.

# 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.

Copy Link

Version

Install

install.packages('geocodebr')

Monthly Downloads

3,230

Version

0.6.1

License

MIT + file LICENSE

Issues

Pull Requests

Stars

Forks

Maintainer

Rafael H. M. Pereira

Last Published

January 27th, 2026

Functions in geocodebr (0.6.1)

busca_por_cep

Busca por CEP
arrow_open_dataset

Safely use arrow to open a Parquet file
definir_campos

Especifica as colunas que descrevem os campos dos endereços
download_cnefe

Faz download dos dados do CNEFE
deletar_pasta_cache

Deletar pasta de cache do geocodebr
definir_pasta_cache

Define um diretório de cache para o geocodebr
geocode

Geolocaliza endereços no Brasil
geocode_reverso

Geocode reverso de coordenadas espaciais no Brasil
listar_pasta_cache

Obtém a pasta de cache usado no geocodebr
listar_dados_cache

Listar dados em cache
update_input_db

Update input_padrao_db to remove observations previously matched
cache_message

Message when caching file
add_precision_col

Add a column with info of geocode match_type
create_index

create index
geocodebr

Package: geocodebr: Geolocalização De Endereços Brasileiros (Geocoding Brazilian Addresses)
apaga_data_release_antigo

Atualiza dados no release local