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. Uma extensão de geocoding como o maps2 resolve esse problema automaticamente: ela 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. O maps2 conecta a tabela tt_address pelo seu registry e reage a cada gravação com um hook DataHandler. Assim que um editor altera um endereço ou cria uma nova localidade, o serviço de geocoding é chamado em segundo plano. O maps2 grava as coordenadas em um registro de localização próprio, vinculado ao endereço, e posiciona a partir dele 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. O tt_address traz o comando CLI ttaddress:geocode, que geocodifica todos os registros sem coordenadas em um lote via Google Geocoding API.

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, um serviço de geocoding 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

O maps2 se integra como hook DataHandler no TYPO3 Core. A extensão monitora as tabelas e os campos de endereço conectados ao seu registry via TCA. Quando um campo de endereço monitorado muda, o maps2 aciona um request de geocoding ao salvar.

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, taxa máxima de 1 request/segundo).

O maps2 armazena as coordenadas em seu próprio registro de localização, nos campos latitude e longitude; o tt_address, em campos decimais de mesmo nome. A extensão pode ser aplicada via configuração TCA a qualquer tabela, não apenas tt_address.

Para busca por raio, o maps2 calcula a distância com uma fórmula SQL no QueryBuilder; uma função Haversine também pode ser incorporada em Extbase Repositories próprios 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: manter o lote abaixo do limite de 3.000 requests por minuto.

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

Uma extensão chamada geocoordinates não está publicada nem no TER nem no Packagist. O maps2, de Stefan Froemken (jweiland.net), traz o geocoding embutido, atualmente 13.1.0 para TYPO3 v14 e 12.2.0 para v13. O tt_address tem seu próprio comando de geocoding, ttaddress:geocode; ambos podem ser usados 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.