Pesquisa e Geocodificação com Google Maps API e a gem Geocoder

Gems
01 de março de 2025

A geolocalização se tornou um recurso essencial em muitas aplicações web, desde sistemas de delivery até plataformas de marketplace. Neste tutorial, vamos explorar como integrar a poderosa Google Maps API com Ruby on Rails utilizando a gem Geocoder para implementar funcionalidades de geocodificação e buscas por proximidade.

O Google Cloud oferece um free tier com créditos gratuitos que permitem testar e utilizar a Google Maps API sem custos iniciais. Essa é a solução mais utilizada pelo mercado devido à sua robustez e suporte, mas existem alternativas totalmente gratuitas, como OpenStreetMap e Mapbox, que podem ser viáveis dependendo do seu caso de uso. Os detalhes e limites podem ser consultados diretamente na página oficial.

O Que é Geocodificação?

A geocodificação é o processo de transformar um endereço textual em coordenadas geográficas que podem ser usadas em sistemas baseados em GPS ou mapas. Por exemplo, o endereço "Av. Paulista, 1000, São Paulo, Brasil" pode ser convertido em latitude e longitude para marcar sua localização em um mapa.

Podemos citar como exemplo a localização de usuários ou estabelecimentos em mapas, a busca de serviços próximos ao usuário e o planejamento de rotas e logística.

Como Implementar Geocodificação em Rails

No ecossistema Ruby on Rails, a gem Geocoder é uma solução popular e fácil de usar para implementar geocodificação ao seu projeto.

1. Instale a Gem Geocoder

Adicione a gem ao seu projeto com o seguinte comando:

bundle add geocoder

2. Configure a API

A gem Geocoder usa APIs de serviços como Google Maps, OpenStreetMap ou Bing para realizar a geocodificação. Configure a chave de API utilizando as credentials do Rails.

Antes de adicionar a chave do Google Maps API, é necessário gerá-la no Google Cloud Console. Siga estes passos:

  1. Acesse o Google Cloud Console.
  2. Faça login com sua conta Google.
  3. Crie um novo projeto ou selecione um existente.
  4. No menu de navegação, vá para "APIs e serviços" e depois "Biblioteca".
  5. Pesquise por "Maps JavaScript API" e clique em "Ativar".
  6. Após ativar a API, acesse a seção "Credenciais".
  7. Clique em "Criar credenciais" e escolha "Chave de API".
  8. Copie a chave gerada e mantenha-a segura.

Com a chave gerada, você pode adicioná-la às credenciais do seu projeto utilizando o seguinte comando:

bin/rails credentials:edit

Adicione a chave na seção apropriada do arquivo de credenciais:

google_maps:
  api_key: "sua_chave_aqui"

Em seguida crie o arquivo config/initializers/geocoder.rb e adicione a configuração do provedor de geolocoding.

Geocoder.configure(
  lookup: :google,  # Provedor de serviço de geocodificação
  api_key: Rails.application.credentials.dig(:google_maps, :api_key),  # Utiliza a chave das credenciais
  use_https: true
)

3. Configure o Model

Escolha o model que armazenará as coordenadas (por exemplo, um modelo Place). Adicione as colunas de latitude e longitude ao banco de dados:

rails generate migration AddCoordinatesToPlaces latitude:float longitude:float
rails db:migrate

Atualize o modelo para incluir a funcionalidade de geocodificação:

# app/models/place.rb
class Place < ApplicationRecord
  geocoded_by :address  # Endereço textual para geocodificação

  after_validation :geocode  # Realiza a geocodificação após validação
end

4. Teste a Geocodificação

No console do Rails (rails console), crie um novo registro:

Place.create(name: "Praia de Copacabana", address: "Av. Atlântica, Copacabana, Rio de Janeiro, Brasil")

Após salvar o registro, o Rails calculará automaticamente as coordenadas de latitude e longitude com base no endereço fornecido.

Implementando Busca por Locais Próximos

Uma funcionalidade comum no uso da geocodificação é exibir locais próximos a uma determinada coordenada. Com a gem Geocoder, essa funcionalidade pode ser facilmente implementada:

# app/controllers/places_controller.rb
class PlacesController < ApplicationController
  def index
    if params[:latitude].present? && params[:longitude].present?
      @places = Place.near([params[:latitude], params[:longitude]], 10)  # Busca locais em um raio de 10 km
    else
      @places = Place.all
    end
  end
end

Antes de implementarmos o formulário de busca, vamos utilizar o componente Stimulus Places Autocomplete para prover a funcionalidade de autocomplete de endereços. Este componente sugere endereços enquanto o usuário digita e permite capturar as coordenadas de latitude e longitude diretamente.

Adicione o componente ao seu projeto:

yarn add stimulus-places-autocomplete

Importe o componente no seu arquivo de inicialização do Stimulus, geralmente localizado em app/javascript/controllers/index.js:

import { Application } from "@hotwired/stimulus"
import PlacesAutocomplete from "stimulus-places-autocomplete"

const application = Application.start()
application.register("places-autocomplete", PlacesAutocomplete)

Com isso configurado, podemos implementar o formulário com os campos de latitude e longitude que serão utilizados como base:

<%= form_with url: places_path, method: :get, local: true, data: { controller: "places-autocomplete" } do %>
  <%= label_tag :location, "Digite sua localização:" %>
  <%= text_field_tag :location, nil, data: { places_autocomplete_target: "input" } %>
  <%= hidden_field_tag :latitude, nil, data: { places_autocomplete_target: "latitude" } %>
  <%= hidden_field_tag :longitude, nil, data: { places_autocomplete_target: "longitude" } %>
  <%= submit_tag "Buscar" %>
<% end %>

A geocodificação é uma funcionalidade que traz grande valor para aplicações modernas, permitindo integrações com mapas e experiências baseadas em localização. Utilizando o Ruby on Rails e a gem Geocoder, é possível implementar essa funcionalidade de forma simples e eficiente.

Se você gostou deste artigo, não deixe de explorar mais conteúdos no blog da Invenio e acompanhar nossas próximas Lives e tutoriais!

Quer aprender mais? Confira nossos cursos na Academia do Ruby para levar suas habilidades de desenvolvimento ao próximo nível!

3 min. de leitura
Top