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.
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")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 .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.
geocode()geocode_reverso()busca_por_cep()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:
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.
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”.
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”.
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
)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.
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.
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).
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:
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:
Pacotes em Python: