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 em R e em Python.

R	Python	Repo

Instalação

R

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("ipea/geocodebr", subdir = "r-package")

Python

A versão Python do {geocodebr} usa o mesmo conjunto de dados e os mesmos nomes de funções do pacote R, com DuckDB como motor tabular principal. No momento, ainda está em desenvolvimento (a publicação no PyPI está planejada). Para instalar localmente:

cd python-package
python -m pip install -e .

Utilização em R

O {geocodebr} possui três funções principais para geolocalização de dados. Os exemplos a seguir utilizam a versão em R do pacote; para a versão Python, consulte a seção Utilização em Python.

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
 )

Utilização em Python

A versão Python do {geocodebr} segue a mesma dinâmica de uso do pacote R, com os mesmos nomes de funções em português. As funções retornam, por padrão, um pyarrow.Table (convertível para pandas com .to_pandas()), ou um geopandas.GeoDataFrame no CRS SIRGAS 2000 (EPSG 4674) com resultado_gpd = TRUE:

import polars as pl
from geocodebr import definir_campos, geocode

enderecos = pl.DataFrame({
    "logradouro": ["RUA PRESIDENTE VARGAS", "AVENIDA PAULISTA"],
    "numero": [123, 1000],
    "cep": ["20080-901", "01310-100"],
    "localidade": ["Centro", "Bela Vista"],
    "municipio": ["RIO DE JANEIRO", "SAO PAULO"],
    "estado": ["RJ", "SP"],
})

campos = definir_campos(
    logradouro="logradouro",
    numero="numero",
    cep="cep",
    localidade="localidade",
    municipio="municipio",
    estado="estado",
)

resultado = geocode(
    enderecos=enderecos,
    campos_endereco=campos,
    resultado_completo=False,
    resolver_empates=True,
    verboso=False,
)

Mais detalhes e exemplos na documentação completa da versão Python.

Windows e performance

No Windows, o geocode() da versão Python pode ser mais lento que em R e deteriorar a cada chamada na mesma sessão: o interpretador Python roda por padrão no heap NT legado, que degrada sob as alocações multithread do DuckDB. O pacote mitiga o problema de duas formas: limitando automaticamente as threads do DuckDB e oferecendo um comando (python -m geocodebr._heap_patch) que cria uma cópia do interpretador com o Segment Heap — em benchmarks internos com 10 milhões de endereços, o tempo total do geocode() caiu de 11:47 para 3:08 minutos. Mais detalhes na seção Windows e performance do README da versão Python.

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 e em Python (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.

Pacotes em R:

• {arcgisgeocode} and {arcgeocoder}: utiliza serviço de geocode do ArcGIS
• {nominatimlite}: baseado dados do OSM
• {photon}: baseado dados do OSM
• {tidygeocoder}: API para diversos servicos de geolocalização
• {googleway} and {mapsapi}: interface para API do Google Maps

Pacotes em Python:

• geopy: cliente para diversos serviços de geocodificação (Nominatim/OSM, Google, ArcGIS, Photon etc.)
• googlemaps: interface para a API do Google Maps
• ArcGIS API for Python: utiliza o serviço de geocodificação do ArcGIS
• opencage: cliente do serviço OpenCage