Geocoding para TYPO3

Por que todo localizador de filiais TYPO3 sem geocoding falha na qualidade dos dados

Localizadores de filiais, busca de revendedores e busca por raio - todos têm o mesmo fundamento: coordenadas GPS. Mas empresas armazenam dados de localização como endereços - rua, número, CEP, cidade. A conversão de endereço para coordenada (geocoding) não acontece sozinha. geocoordinates resolve esse problema automaticamente: a extensão monitora campos de endereço em registros TYPO3 e calcula a cada alteração as coordenadas GPS correspondentes via serviço de geocoding.

Sem extensão de geocoding, editores teriam que copiar manualmente latitude e longitude do Google Maps para cada localidade. Com 50 localidades, isso é uma hora de trabalho. Com 500 localidades, um dia inteiro - e a cada mudança de endereço, o processo recomeça.

Cenários típicos de uso

Geocoding automático para registros tt_address. Uma empresa com 120 localidades na região mantém todos os endereços na extensão TYPO3 tt_address. geocoordinates registra um hook DataHandler na tabela tt_address. Assim que um editor altera um endereço ou cria uma nova localidade, o serviço de geocoding é chamado em segundo plano. As coordenadas são escritas nos campos latitude e longitude do banco de dados. A extensão de mapa maps2 lê esses campos e posiciona o marcador no lugar correto.

Geocoding em lote em migrações de dados. Uma empresa migra 2.000 endereços de um sistema antigo para TYPO3. Os registros importados têm rua e CEP, mas sem coordenadas. geocoordinates oferece um comando CLI que geocodifica todos os registros sem coordenadas em um lote.

Busca por raio baseada em CEP. Uma empresa de serviços oferece busca por raio: “Encontre o parceiro mais próximo.” O visitante digita seu CEP, geocoordinates converte o CEP em coordenadas, e um cálculo de distância SQL (fórmula Haversine) retorna todas as localidades no raio de 25, 50 ou 100 km, ordenadas por distância.

Arquitetura técnica

geocoordinates se integra como hook DataHandler no TYPO3 Core. A extensão monitora tabelas e campos configuráveis. Quando um campo de endereço monitorado muda, um request de geocoding é acionado assincronamente.

A extensão suporta dois provedores de geocoding: Google Geocoding API (alta precisão, disponível mundialmente, requer API Key com billing ativado) e OpenStreetMap Nominatim (gratuito, sem registro necessário, em conformidade com LGPD (PT: RGPD), taxa máxima de 1 request/segundo).

As coordenadas são armazenadas em campos de banco de dados configuráveis. A extensão pode ser aplicada via configuração TCA a qualquer tabela, não apenas tt_address.

Para busca por raio, geocoordinates disponibiliza uma função de distância Haversine que pode ser incorporada em Extbase Repositories ou queries QueryBuilder diretas. O cálculo ocorre no nível do banco de dados (MySQL/MariaDB), não em PHP. Isso é crítico para performance: um cálculo de distância via PHP sobre 10.000 localidades leva segundos, um cálculo SQL com índice leva milissegundos.

Problemas frequentes e soluções

Geocoding retorna coordenadas erradas para endereços. Endereços com caracteres especiais podem causar problemas quando a API não processa corretamente a codificação. Solução: garantir que os dados de endereço sejam enviados em UTF-8 para a API.

Google Geocoding API retorna “OVER_QUERY_LIMIT”. Em geocoding em lote com mais de 50 requests por segundo, o Google limita a API. Solução: ativar rate-limiting no comando de lote (máx. 40 requests/segundo para contas padrão).

Nominatim retorna resultados diferentes para o mesmo endereço. Dados OpenStreetMap são mantidos pela comunidade e podem mudar. Solução: marcar coordenadas já geocodificadas como “verificadas” e re-geocodificar apenas em mudança manual do endereço.

Migração e compatibilidade de versões

geocoordinates está disponível como pacote Composer para TYPO3 v10 a v12. A extensão é mantida por Stefan Froemken, que também desenvolve maps2. As duas extensões são coordenadas entre si mas podem ser usadas independentemente.

A Gosign combina geocoordinates por padrão com maps2 para entregar um stack completo de localizador de filiais: entrada de endereço pelo editor, geocoding automático em segundo plano, exibição de mapa com marcador e popup no frontend, busca por raio com entrada de CEP para o visitante. O stack é configurado em 2 a 3 dias e cobre os requisitos de 90% de todos os projetos de localizador de filiais.