Geocoding para TYPO3

Por qué todo buscador de sucursales TYPO3 sin geocodificación fracasa por la calidad de datos

Los buscadores de sucursales, la búsqueda de distribuidores y la búsqueda por radio tienen el mismo fundamento: coordenadas GPS. Pero las empresas almacenan datos de ubicación como direcciones - calle, número, código postal, ciudad. La conversión de dirección a coordenada (geocodificación) no ocurre sola. Una extensión de geocodificación como maps2 resuelve este problema de forma automatizada: monitoriza campos de dirección en registros TYPO3 y calcula las coordenadas GPS correspondientes vía servicio de geocodificación ante cada cambio.

Sin extensión de geocodificación, los editores tendrían que copiar manualmente latitud y longitud de Google Maps para cada ubicación. Con 50 sedes, eso es una hora de trabajo. Con 500 sedes, un día completo - y con cada cambio de dirección el proceso empieza de nuevo.

Escenarios de uso habituales

Geocodificación automática para registros tt_address. Una empresa con 120 sedes en España gestiona todas las direcciones en la extensión TYPO3 tt_address. maps2 conecta la tabla tt_address mediante su registry y reacciona a cada guardado con un hook DataHandler. En cuanto un editor cambia una dirección o crea una nueva sede, se llama al servicio de geocodificación en segundo plano. maps2 guarda las coordenadas en un registro de ubicación propio vinculado a la dirección y coloca a partir de él el marcador en la posición correcta.

Geocodificación por lotes en migraciones de datos. Una empresa migra 2.000 direcciones de un sistema antiguo a TYPO3. Los registros importados tienen calle y código postal pero no coordenadas. tt_address trae el comando CLI ttaddress:geocode, que geocodifica todos los registros sin coordenadas en un lote mediante la Google Geocoding API.

Búsqueda por radio basada en códigos postales. Un taller ofrece búsqueda por radio: “Encuentra el partner más cercano.” El visitante introduce su código postal, un servicio de geocodificación lo convierte en coordenadas, y un cálculo de distancia SQL (fórmula de Haversine) devuelve todas las sedes en un radio de 25, 50 o 100 km, ordenadas por distancia.

Arquitectura técnica

maps2 se integra como hook DataHandler en el TYPO3 Core. La extensión monitoriza las tablas y los campos de dirección conectados a su registry mediante TCA. Cuando cambia un campo de dirección monitorizado, maps2 lanza una petición de geocodificación al guardar.

La extensión soporta dos proveedores: Google Geocoding API (alta precisión, disponible mundialmente, requiere API key con facturación activada, 5 USD por 1.000 peticiones, gratuito hasta 10.000/mes desde marzo de 2025) y OpenStreetMap Nominatim (gratuito, sin registro, limitación de 1 petición/segundo).

maps2 almacena las coordenadas en su propio registro de ubicación, en los campos latitude y longitude; tt_address, en campos decimales del mismo nombre. Para la búsqueda por radio, maps2 calcula la distancia con una fórmula SQL que se ejecuta a nivel de base de datos, no en PHP - algo crítico para el rendimiento con grandes volúmenes de datos.

Problemas frecuentes y soluciones

La geocodificación devuelve coordenadas incorrectas para direcciones españolas. Las direcciones con caracteres especiales (tildes, ñ) pueden causar problemas si la API no procesa correctamente la codificación de caracteres. Solución: asegurar que los datos de dirección se envían a la API en UTF-8.

La Google Geocoding API devuelve “OVER_QUERY_LIMIT”. Con geocodificación por lotes de más de 50 peticiones por segundo, Google limita la API. Solución: mantenerse en el lote por debajo del límite de 3.000 peticiones por minuto.

Nominatim devuelve resultados diferentes para la misma dirección. Los datos de OpenStreetMap son mantenidos por la comunidad y pueden cambiar. Solución: marcar las coordenadas ya geocodificadas como “verificadas” y solo volver a geocodificar cuando cambie manualmente la dirección.

Migración y compatibilidad de versiones

Una extensión llamada geocoordinates no está publicada ni en el TER ni en Packagist. maps2, de Stefan Froemken (jweiland.net), trae el geocoding incluido, actualmente 13.1.0 para TYPO3 v14 y 12.2.0 para v13. tt_address tiene su propio comando de geocoding, ttaddress:geocode; ambas pueden usarse independientemente.

Gosign combina geocoordinates con maps2 como estándar para entregar un stack completo de buscador de sucursales: entrada de dirección por el editor, geocodificación automática en segundo plano, visualización en mapa con marcador y popup en frontend, búsqueda por radio con entrada de código postal para el visitante. El stack se configura en 2 a 3 días y cubre los requisitos del 90 % de los proyectos de buscador de sucursales.