Olá devs! ❤️
Você tem uma lista de endereços e precisa descobrir a latitude e a longitude de cada um?
Isso é chamado de geocodificação!
E olha que legal: existe uma ferramenta brasileira que permite fazer isso gratuitamente, usando dados públicos do IBGE.
No artigo de hoje, vamos colocar a mão na massa e descobrir como transformar um endereço brasileiro em coordenadas geográficas usando Python e dados públicos do IBGE, sem depender de uma API comercial para cada consulta.
Para tornar o exemplo concreto, vamos usar o endereço do Jardim Botânico de Curitiba, no Paraná.
🥰 Siga nossa página no Linkedin e no Instagram e ajude a divulgar nosso conteúdo. Por mais mulheres em tech!
Veja também:
- Como eu construí um escritório virtual em pixel art com 3 arquivos e zero bibliotecas
- Quer estudar Ciência de Dados sem gastar com cursos?
- Coloquei o Laya para jogar o jogo do dinossauro do Chrome!
- E se um buraco negro fosse seu lembrete para fazer uma pausa? 😅
- 5 Design Patterns (Padrões de Projeto) que toda programadora deveria conhecer
1. Instalando o geocodebr
Neste tutorial, vamos colocar a mão na massa com o geocodebr, um pacote Python desenvolvido pelo IPEA para geocodificar endereços brasileiros usando dados do Cadastro Nacional de Endereços para Fins Estatísticos (CNEFE), do IBGE.
Vamos começar instalando as dependências. Neste exemplo, utilizarei uv para gerenciar o ambiente Python.
No terminal, execute:
uv init geocodebr-tutorial --python 3.12
cd geocodebr-tutorial
uv add geocodebr polars pandasO geocodebr utiliza os dados do CNEFE para encontrar correspondências entre os endereços informados e os registros disponíveis.
Na primeira execução, ele poderá baixar uma quantidade considerável de dados, portanto, reserve alguns minutos para essa etapa.
2. Preparando o endereço
Nosso exemplo será o Jardim Botânico de Curitiba, localizado na Rua Engenheiro Ostoja Roguski, 350.
Vamos representar o endereço em uma tabela usando Polars.
Abra o arquivo main.py no editor de código e adicione o seguinte trecho. Ele cria uma tabela com os componentes do endereço que queremos geocodificar:
import polars as pl
enderecos = pl.DataFrame({
"logradouro": ["RUA ENGENHEIRO OSTOJA ROGUSKI"],
"numero": [350],
"cep": ["80210-391"],
"localidade": ["JARDIM BOTANICO"],
"municipio": ["CURITIBA"],
"estado": ["PR"],
})
print(enderecos)E execute:
uv run python main.pyObserve que dividimos o endereço em campos estruturados: logradouro, número, CEP, bairro, município e estado.
Essa organização é importante porque o geocodificador utiliza essas informações para procurar correspondências na base de endereços.
3. Executando a geocodificação
Agora vem a parte principal!
Vamos informar ao pacote quais colunas representam cada componente do endereço e executar a geocodificação.
Abra o arquivo main.py novamente e adicione o código abaixo ao final do arquivo, mantendo o código da etapa anterior.
Vamos informar ao pacote quais colunas representam cada componente do endereço e executar a geocodificação.
from geocodebr import definir_campos, geocode
campos = definir_campos(
logradouro="logradouro",
numero="numero",
cep="cep",
localidade="localidade",
municipio="municipio",
estado="estado",
)
resultado = geocode(
enderecos=enderecos,
campos_endereco=campos,
resultado_completo=True,
resolver_empates=True,
verboso=True,
)
df = resultado.to_pandas()
print(df.to_string(index=False))Execute novamente:
uv run python main.pyVamos entender os parâmetros mais importantes:
definir_campos(): informa ao pacote quais colunas contêm os componentes do endereço.resultado_completo=True: solicita informações adicionais sobre a correspondência encontrada.resolver_empates=True: habilita a resolução de situações em que há mais de uma correspondência candidata.verboso=True: exibe mensagens sobre o andamento do processamento.
Na primeira execução, o pacote poderá baixar os dados do CNEFE e preparar as informações antes de realizar a busca.
O resultado: 🎉
logradouro numero cep localidade municipio estado lat lon precisao tipo_resultado desvio_metros endereco_encontrado logradouro_encontrado numero_encontrado cep_encontrado localidade_encontrada municipio_encontrado estado_encontrado similaridade_logradouro contagem_cnefe empate cod_setor
RUA ENGENHEIRO OSTOJA ROGUSKI 350 80210-391 JARDIM BOTANICO CURITIBA PR -25.441392 -49.240734 numero_aproximado da03 33 RUA ENGENHEIRO OSTOJA ROGUSKI, 350 (aprox) - JARDIM BOTANICO, CURITIBA - PR RUA ENGENHEIRO OSTOJA ROGUSKI NaN NaN JARDIM BOTANICO CURITIBA PR 1.0 1 False 4106902050101394. Interpretando o resultado
No nosso experimento, o geocodebr retornou as seguintes coordenadas para o endereço informado:
- Latitude:
-25.441392 - Longitude:
-49.240734 - Precisão:
numero_aproximado - Desvio estimado: 33 metros
- Similaridade do logradouro: 1.0
Latitude e longitude identificam uma posição geográfica. A latitude indica a posição norte-sul, enquanto a longitude indica a posição leste-oeste.
Mas há um detalhe importante: uma correspondência textual perfeita não significa necessariamente que a coordenada seja exata.
Embora a similaridade do logradouro tenha sido 1.0, o pacote classificou a precisão como numero_aproximado e informou um desvio estimado de 33 metros.
Essa distinção é importante quando trabalhamos com dados geográficos.
O resultado deve ser interpretado considerando a qualidade da correspondência, e não apenas a existência de coordenadas.
🎁 Receba nossos recursos gratuitos!
Ao assinar nossa newsletter gratuitamente, você terá acesso à nossa biblioteca de recursos, com guias rápidos, e-book, e outros materiais.
👉 https://mulheresprogramando.substack.com/subscribe
Após se inscrever, você receberá um e-mail de boas-vindas com o link para a página de recursos.
5. Visualizando o resultado em um mapa
Depois de obter as coordenadas, podemos visualizá-las em um mapa interativo.
A geocodificação e a visualização são etapas diferentes: o geocodebr encontra as coordenadas, enquanto uma biblioteca de mapas as apresenta visualmente.
Uma alternativa é utilizar o MapLibre GL JS com o OpenFreeMap, que permite criar mapas interativos sem precisar de uma chave de API do Google.
Vamos aproveitar a latitude e a longitude retornadas pelo geocodebr para centralizar o mapa e adicionar um marcador ao endereço encontrado.
Para continuar, crie um arquivo chamado mapa.html e acrescente o código a seguir no arquivo.
Esse código utilizará o resultado da geocodificação para gerar a visualização do mapa.
<!DOCTYPE html>
<html lang="pt-BR">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Endereço geocodificado</title>
<link href="https://unpkg.com/maplibre-gl@5.6.2/dist/maplibre-gl.css"
rel="stylesheet">
<script src="https://unpkg.com/maplibre-gl@5.6.2/dist/maplibre-gl.js"></script>
<style>
body {
margin: 0;
font-family: Arial, sans-serif;
}
h2 {
padding: 12px 20px;
}
#map {
width: 100%;
height: 600px;
}
</style>
</head>
<body>
<h2>Localização do endereço geocodificado</h2>
<div id="map"></div>
<script>
// Coordenadas retornadas pelo geocodebr
const latitude = -25.441392;
const longitude = -49.240734;
const map = new maplibregl.Map({
container: "map",
style: "https://tiles.openfreemap.org/styles/liberty",
center: [longitude, latitude],
zoom: 16
});
map.addControl(new maplibregl.NavigationControl());
new maplibregl.Marker({ color: "#d62828" })
.setLngLat([longitude, latitude])
.setPopup(
new maplibregl.Popup().setText(
"Rua Engenheiro Ostoja Roguski, 350 — Curitiba"
)
)
.addTo(map);
</script>
</body>
</html>Abra o arquivo mapa.html para ver no navegador. Ele deve abrir:
Conclusão
O geocodebr oferece uma alternativa interessante para quem precisa geocodificar endereços brasileiros usando Python e dados públicos do IBGE.
Neste exemplo, partimos de um endereço estruturado, executamos a geocodificação e obtivemos coordenadas acompanhadas de informações sobre a precisão da correspondência.
Para quem trabalha com ciência de dados, pesquisa ou análise territorial, esse processo pode ser útil para preparar bases de endereços antes de realizar análises espaciais e construir visualizações geográficas.
Você pode consultar a documentação e explorar outros exemplos no site oficial do geocodebr e no repositório do projeto no GitHub.
O mais interessante é que esse fluxo pode ser adaptado para bases maiores, desde que os endereços estejam adequadamente estruturados e que a cobertura dos dados seja suficiente para o caso de uso. 🚀
Espero que tenham gostao e até o próximo artigo!
