geocodebr Python: Geolocalização de Endereços Brasileiros

Versão Python do geocodebr, usando DuckDB como motor tabular principal. A proposta é preservar a dinâmica de uso do pacote R, incluindo nomes de funções em português, mantendo o processamento interno em SQL/DuckDB para boa performance e menor uso de memória.

O pacote geolocaliza endereços brasileiros sem limite de número de consultas, com base em dados abertos do CNEFE (Cadastro Nacional de Endereços para Fins Estatísticos), publicado pelo IBGE.

Instalação

O pacote está disponível no PyPI:

python -m pip install geocodebr

Para usar geocode_reverso() ou receber o resultado como geopandas.GeoDataFrame (resultado_gpd=True), instale o extra geo:

python -m pip install "geocodebr[geo]"

Para instalar a partir do código-fonte deste repositório:

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

Dependências principais:

• duckdb: motor principal de dados e SQL.
• pyarrow: formato padrão de retorno e interoperabilidade com Parquet.
• enderecobr: padronização dos endereços, garantindo paridade com o pacote R.
• polars: processamento tabular interno, usado para integrar o enderecobr.
• requests: download dos dados do CNEFE.
• h3: criação opcional de células H3.

Utilização

O pacote possui três funções principais:

1. geocode()
2. geocode_reverso()
3. busca_por_cep()

As funções retornam, por padrão, um pyarrow.Table. Caso precise converter para pandas, use .to_pandas() no resultado final. Passando resultado_gpd=True, o retorno é um geopandas.GeoDataFrame de pontos no CRS SIRGAS 2000 (EPSG 4674), equivalente ao sf do pacote R. Esse retorno exige o extra geo na instalação (python -m pip install geocodebr[geo]).

1. Geolocalização: de endereços para coordenadas

Primeiro, indique quais colunas da sua tabela representam cada campo do endereço usando definir_campos(). Depois, chame geocode().

Por padrão, os endereços são padronizados internamente pela função enderecobr_padronizar_enderecos(), o que é essencial para uma geolocalização correta. O primeiro uso pode baixar os dados do CNEFE para o cache local.

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,
    h3_res=[8, 10],
    verboso=False,
)

print(resultado.schema.names)
print(resultado.to_pandas().head())

Também é possível passar diretamente um caminho para arquivo .csv ou .parquet:

resultado = geocode(
    enderecos="caminho/para/enderecos.csv",
    campos_endereco=campos,
    verboso=False,
)

O resultado preserva as colunas originais e adiciona, entre outras:

• lat
• lon
• precisao
• tipo_resultado
• desvio_metros
• endereco_encontrado

Com resultado_completo=True, também retorna campos encontrados no CNEFE, como logradouro_encontrado, numero_encontrado, cep_encontrado, localidade_encontrada, municipio_encontrado, estado_encontrado, similaridade_logradouro, contagem_cnefe, empate e cod_setor.

2. Geolocalização reversa: de coordenadas para endereços

geocode_reverso() busca o endereço mais próximo de cada ponto dentro de uma distância máxima em metros. Assim como no R, a entrada deve ser um GeoDataFrame de pontos no CRS SIRGAS 2000 (EPSG:4674), e o retorno é o próprio GeoDataFrame de input acrescido dos campos do endereço encontrado e da coluna distancia_metros. Esta função requer o extra geo (pip install geocodebr[geo]).

import geopandas as gpd

from geocodebr import geocode_reverso

pontos = gpd.GeoDataFrame(
    {"id": [1, 2]},
    geometry=gpd.points_from_xy([-47.9001, -43.2001], [-15.8001, -22.9001]),
    crs="EPSG:4674",
)

enderecos_proximos = geocode_reverso(
    pontos=pontos,
    dist_max=1000,
    verboso=False,
)

print(enderecos_proximos)

O resultado inclui os campos do endereço encontrado e a coluna distancia_metros.

3. Busca por CEP

busca_por_cep() retorna os endereços associados a um ou mais CEPs.

from geocodebr import busca_por_cep

ceps = ["70390-025", "20071-001", "99999-999"]

resultado_cep = busca_por_cep(
    cep=ceps,
    h3_res=10,
    verboso=False,
)

print(resultado_cep.to_pandas())

O resultado inclui:

• cep
• estado
• municipio
• logradouro
• localidade
• lon
• lat

Se h3_res for informado, o pacote adiciona colunas como h3_08 ou h3_10.

Padronização de endereços

A função enderecobr_padronizar_enderecos() também está disponível publicamente, para padronizar os endereços antes da geolocalização (ou usá-la de forma independente). Ela recebe um polars.DataFrame e o dicionário criado com definir_campos(), e adiciona as colunas *_padr:

from geocodebr import enderecobr_padronizar_enderecos

enderecos_padrao = enderecobr_padronizar_enderecos(
    enderecos=enderecos,
    campos_do_endereco=campos,
    formato_estados="sigla",
    formato_numeros="integer",
    manter_cols_extras=True,
)

Se os seus dados já estiverem padronizados (ou seja, já contiverem as colunas *_padr), chame geocode(..., padronizar_enderecos=False) para pular essa etapa.

Precisão dos resultados

Os resultados do geocode() são classificados em seis categorias de precisao ("numero", "numero_aproximado", "logradouro", "cep", "localidade" e "municipio"), desagregadas em códigos de tipo_resultado (e.g. dn01, pa03), e incluem a coluna desvio_metros, com uma estimativa da incerteza da localização encontrada. A interpretação dessas colunas, o significado de cada código e as regras de resolução de empates estão documentadas na vignette "geocode".

Cache dos dados do CNEFE

Na primeira execução, o pacote baixa arquivos Parquet do release do CNEFE usado pelo geocodebr. Esses arquivos ficam em cache local para acelerar chamadas futuras.

from geocodebr import (
    definir_pasta_cache,
    listar_pasta_cache,
    listar_dados_cache,
    deletar_pasta_cache,
    download_cnefe,
)

print(listar_pasta_cache())

download_cnefe(tabela="municipio_logradouro_cep_localidade", verboso=True)

arquivos = listar_dados_cache()
print(arquivos)

# definir uma pasta de cache específica
definir_pasta_cache("D:/dados/geocodebr-cache", verboso=True)

# apagar cache configurado
# deletar_pasta_cache()

Processamento interno (DuckDB-first)

Esta versão evita usar pandas no pipeline interno. O fluxo principal registra as entradas no DuckDB, executa joins/filtros/matches em SQL e só materializa o resultado no final como pyarrow.Table.

A padronização dos endereços é a única etapa fora do DuckDB: é feita em polars, fazendo a ponte com os bindings Python do enderecobr, sem materializar pandas em nenhum momento.

Isso facilita a paridade com o pacote R, que também usa DuckDB para o motor de geocodificação, e ajuda em bases maiores.

Windows e performance

No Windows, o python.exe roda por padrão no heap NT legacy e não no mais moderno e eficaz Segment Heap. O heap legado degrada sob alocação multithread intensa do DuckDB: o geocode() fica mais lento e piora a cada chamada na mesma sessão (contexto em duckdb/duckdb#24027 e no relatório de diagnóstico do pacote).

O pacote mitiga o problema de duas formas:

1. Limitação automática de threads — no Windows sem Segment Heap, se n_cores não for definido, o geocode() limita o DuckDB a min(4, núcleos da máquina) threads (mínimo da curva tempo x threads no heap legacy, confirmado por sweep com o workload canônico do duckdb#24027 — benchmarks/verifica_sweep_threads.py; bacia plana entre 3 e 6 threads) e emite um aviso uma vez por sessão. Um n_cores passado de forma explícita é respeitado.

2. Interpretador com Segment Heap (recomendado) — usuário pode gerar uma cópia do interpretador Python com o manifesto patcheado com o Segment Heap e rodar o geocode() a partir dele. Para criar a cópia, basta rodar:

   python -m geocodebr._heap_patch
   

   O comando cria o arquivo python-geocodebr-sh.exe ao lado do interpretador base (python.exe), sem alterar o original. Inicie a sessão pela cópia para que o DuckDB use o Segment Heap.

   Em benchmarks internos com 10 milhões de endereços, o tempo total do geocode() caiu de 11:47 minutos para 3:08 minutos.

Limitações conhecidas das soluções apresentadas para uso do geocodebr no Windows:

• Interpretador com Segment Heap requer Windows 10 (build 19041) ou superior.

• Não existe configuração do Windows (variável de ambiente ou registro) que ligue o Segment Heap por processo. A camada de compatibilidade — via __COMPAT_LAYER=SEGMENTHEAP ou persistida no registro (AppCompatFlags\Layers / Image File Execution Options) — não alcança o heap criado no startup, por onde passam as alocações do DuckDB.

• O ganho vale apenas para sessões iniciadas pela cópia (python-geocodebr-sh.exe); Jupyter/IDEs que lançam outro interpretador não se beneficiam.

• A cópia é criada na pasta do interpretador base; se ela não for gravável (ex.: Program Files), execute o terminal como administrador ou use uma instalação por usuário (ex.: uv, pyenv).

• A cópia usa os pacotes do ambiente base. Com geocodebr instalado em venv, aponte PYTHONPATH para o site-packages da venv. Exemplo em PowerShell:

   $env:PYTHONPATH = "C:\caminho\para\.venv\Lib\site-packages"; & "C:\caminho\para\python-geocodebr-sh.exe" "C:\caminho\para\seu_script.py"
  

• A limitação de threads reduz a contenção do heap, mas não elimina a deterioração entre chamadas sucessivas na mesma sessão; a cópia com Segment Heap resolve os dois problemas.

Desenvolvimento e testes

Para rodar a suíte de testes:

uv run pytest -q -m "not r_parity"

Esse comando roda apenas os testes unitários, com Parquets sintéticos, sem baixar dados do CNEFE.

Testes de paridade R vs Python

O pacote também inclui testes que comparam a saída do Python com a saída do pacote R usando os dados de exemplo inst/extdata/small_sample.csv e inst/extdata/large_sample.parquet.

Esses testes exigem Rscript no PATH, instalam o pacote R localmente em uma biblioteca temporária e podem baixar dados do CNEFE. Se Rscript não estiver disponível, eles são pulados automaticamente.

uv run pytest -m r_parity -q

Exemplos

A pasta exemplos/ contém scripts simples usando as funções principais da versão Python:

• geocode_enderecos.py: busca coordenadas a partir de endereços.
• busca_por_cep.py: busca endereços/coordenadas a partir de CEPs.
• geocode_reverso.py: busca endereço próximo a coordenadas.

Execute os exemplos a partir da raiz do repositório:

uv run python exemplos/geocode_enderecos.py
uv run python exemplos/busca_por_cep.py
uv run python exemplos/geocode_reverso.py

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

• 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