Neste tutorial, você vai aprender como encontrar as coordenadas (latitude e longitude) de um endereço a partir do valor de CEP em poucas linhas de código, utilizando a API do Bing Maps e a biblioteca Python Geocoder.

A ideia do tutorial surgiu quando tive que implementar uma solução parecida em um projeto na minha equipe, e passei um bom tempo tentando encontrar a melhor solução para endereços brasileiros.

Para que possamos utilizar dados anonimizados, vamos nos basear no dataset do projeto open source OpenAddresses, que fornece endereços em diferentes países ao redor do mundo, e, neste caso, olhando especificamente para a América do Sul.

No entanto, para nosso caso em específico, preparei um dataset que será utilizado neste tutorial: address.csv

API Bing Maps

Como a API fornecida pelo Google Maps possui limitações para o plano gratuito, decidi optar pela API da Bing Maps, que além de ser gratuita, tem uma forma muito intuitiva para a criação de chaves de acesso.

No site, basta fazer o cadastro de usuário, caso ainda não possua uma conta registrada. Seremos então redirecionados para o portal Dev Center. Lá, basta selecionar My account > My keys.

No menu das chaves de acesso, clique para criar uma nova chave:

Para a criação da chave, você pode fornecer um nome associado à sua aplicação, bem como a URL de acesso (que não usaremos neste tutorial), o tipo de chave e o tipo de aplicação.

Após criada, a chave de acesso ficará disponível no menu My keys para que possa ser utilizada nas suas aplicações.

Colocando a mão na massa com Geocoder

Tendo o valor da chave de acesso, podemos colocar a mão na massa. Para este tutorial, foi utilizado o Google Colab, porém, você pode utilizar o Jupyter Notebook ou o seu editor de texto/IDE preferidos.

Começaremos com a transformação do dataset em um DataFrame pandas:

import pandas as pd

df_address = pd.read_csv('address.csv')

Faremos a instalação da biblioteca utilizando o pacote Pip:

!pip install geocoder

Por fim, utilizaremos o Geocoder para criar duas novas colunas no nosso DataFrame para popular os valores das coordenadas naquele determinado CEP. A solução será iterar cada registro utilizando o método iterrows() do pandas:

import geocoder

MY_KEY = '<put_api_access_key_here>'

df_address['latitude'] = ""
df_address['longitude'] = ""

for index, row in df_address.iterrows():
  g = geocoder.bing(location = (row['postcode']).replace('-', ''), 
                                postalCode = (row['postcode']).replace('-', ''), 
                                locality = row['city'], 
                                adminDistrict = row['state'], 
                                countryRegion = 'BRA', 
                                key = MY_KEY)

  df_address['latitude'].iloc[index] = g.lat
  df_address['longitude'].iloc[index] = g.lng

Com isso, o resultado final será a informação completa sobre cada endereço contido no DataFrame. Informações sobre coordenadas podem nos auxiliar para cálculo de distância entre endereços, como por exemplo.

Caso você queira exportar novamente para o formato CSV, basta utilizar o método do pandas to_csv(), também sendo possível aplicar o to_excel() para gerar uma planilha eletrônica com a extensão “.xlsx”.

df_address.to_csv('complete_address.csv', index=False)

Pronto! Muito simples, não é? :)

Após algumas tentativas com diversas bibliotecas Python voltadas para geolocalização, a Geocoder foi a que funcionou melhor para o meu projeto, visto que é bem completa e possibilita a utilização de diversos provedores existentes por aí.

Espero que tenham gostado do tutorial e que possa auxiliá-los em projetos futuros. Nos vemos por aí! 💜

Para ler a documentação completa do Geocoder, acesse o link a seguir:

Caso você queira o código completo, segue o link do notebook no GitHub: Bing_Maps_and_Geocoder_Tutorial.ipynb