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. geocoordinates resuelve este problema de forma automatizada: la extensión 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. geocoordinates registra un hook DataHandler en la tabla tt_address. En cuanto un editor cambia una dirección o crea una nueva sede, se llama al servicio de geocodificación en segundo plano. Las coordenadas se escriben en los campos de base de datos latitude y longitude. La extensión de mapas maps2 lee estos campos y coloca 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. geocoordinates ofrece un comando CLI que geocodifica todos los registros sin coordenadas en un lote.

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, geocoordinates 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

geocoordinates se integra como hook DataHandler en el TYPO3 Core. La extensión monitoriza tablas y campos configurables. Cuando cambia un campo de dirección monitorizado, se lanza asíncronamente una petición de geocodificación.

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 40.000/mes) y OpenStreetMap Nominatim (gratuito, sin registro, limitación de 1 petición/segundo, conforme al RGPD al no transferir datos personales fuera de Europa, alineado con los criterios de la AEPD).

Las coordenadas se almacenan en campos de base de datos configurables (estándar: latitude y longitude como campos DOUBLE). Para la búsqueda por radio, geocoordinates proporciona una función de distancia Haversine 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: activar rate limiting en el comando de lotes (máx. 40 peticiones/segundo para cuentas estándar).

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

geocoordinates está disponible como paquete Composer para TYPO3 v10 a v12. La extensión la mantiene Stefan Froemken, quien también desarrolla maps2. Ambas extensiones están coordinadas entre sí pero 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.