Geocoding dla TYPO3

Dlaczego każda wyszukiwarka oddziałów TYPO3 bez geocodingu nie daje rady z jakością danych

Wyszukiwarki oddziałów, wyszukiwanie dealerów i wyszukiwanie w okolicy mają tę samą podstawę: współrzędne GPS. Ale firmy przechowują dane lokalizacji jako adresy - ulica, numer, kod pocztowy, miasto. Przeliczenie adresu na współrzędne (geocoding) nie dzieje się samo. geocoordinates rozwiązuje ten problem automatycznie: rozszerzenie monitoruje pola adresowe w rekordach TYPO3 i przy każdej zmianie oblicza odpowiednie współrzędne GPS przez serwis geocodingowy.

Bez rozszerzenia geocodingowego redaktorzy musieliby dla każdej lokalizacji ręcznie kopiować szerokość i długość geograficzną z Google Maps. Przy 50 lokalizacjach to godzina pracy. Przy 500 lokalizacjach cały dzień roboczy - i przy każdej zmianie adresu proces zaczyna się od nowa.

Typowe scenariusze zastosowań

Automatyczne geocodowanie rekordów tt_address. Firma ze 120 lokalizacjami w Polsce, Niemczech i Czechach zarządza wszystkimi adresami w rozszerzeniu TYPO3 tt_address. geocoordinates rejestruje DataHandler-Hook na tabelę tt_address. Gdy redaktor zmieni adres lub utworzy nową lokalizację, w tle wywoływany jest serwis geocodingowy. Współrzędne są zapisywane w polach bazy danych latitude i longitude. Rozszerzenie map maps2 odczytuje te pola i umieszcza marker we właściwym miejscu.

Batch-Geocoding przy migracjach danych. Firma migruje 2000 adresów ze starego systemu do TYPO3. Zaimportowane rekordy mają ulicę i kod pocztowy, ale nie współrzędne. geocoordinates oferuje komendę CLI, która geokoduje wszystkie rekordy bez współrzędnych w jednym przebiegu batchowym.

Wyszukiwanie w okolicy na podstawie kodów pocztowych. Firma rzemieślnicza oferuje wyszukiwanie w okolicy: “Znajdź najbliższego partnera w swojej okolicy.” Odwiedzający wpisuje kod pocztowy, geocoordinates konwertuje kod na współrzędne i obliczenie odległości SQL (formuła Haversine) dostarcza wszystkie lokalizacje w promieniu 25, 50 lub 100 km, posortowane według odległości.

Architektura techniczna

geocoordinates integruje się jako DataHandler-Hook w TYPO3 Core. Rozszerzenie monitoruje konfigurowalne tabele i pola. Gdy monitorowane pole adresowe się zmieni, asynchronicznie wyzwalane jest żądanie geocodingu.

Rozszerzenie wspiera dwóch dostawców geocodingu: Google Geocoding API (wysoka dokładność, dostępne globalnie, wymaga klucza API z aktywnym rozliczeniem, 5 USD za 1000 żądań) oraz OpenStreetMap Nominatim (bezpłatne, bez rejestracji, ale ograniczenie do 1 żądania/sekundę i nieco niższa dokładność w obszarach wiejskich).

Współrzędne są przechowywane w konfigurowalnych polach bazodanowych. Dla wyszukiwania w okolicy geocoordinates udostępnia funkcję odległości Haversine, którą można wbudować w repozytoria Extbase lub bezpośrednie zapytania QueryBuilder. Obliczenie odbywa się na poziomie bazy danych (MySQL/MariaDB), nie w PHP - to krytyczne dla wydajności.

Częste problemy i rozwiązania

Geocoding dostarcza błędne współrzędne dla polskich adresów. Polskie adresy ze znakami diakrytycznymi (ą, ę, ł, ś, ż) mogą powodować problemy, gdy API nie przetwarza prawidłowo kodowania znaków. Rozwiązanie: upewnienie się, że dane adresowe są wysyłane do API w UTF-8. geocoordinates koduje domyślnie w UTF-8, ale pola bazy danych z kodowaniem Latin1 mogą tu przeszkadzać.

Google Geocoding API zwraca “OVER_QUERY_LIMIT”. Przy batch-geocodingu z ponad 50 żądaniami na sekundę Google ogranicza API. Rozwiązanie: aktywacja rate-limiting w komendzie batchowej (maks. 40 żądań/sekundę dla kont standardowych).

Nominatim przy tym samym adresie zwraca różne wyniki. Dane OpenStreetMap są pielęgnowane przez społeczność i mogą się zmieniać. Rozwiązanie: oznaczenie raz geokodowanych współrzędnych jako “zweryfikowane” i ponowne geokodowanie tylko przy ręcznej zmianie adresu.

Migracja i kompatybilność wersji

geocoordinates jest dostępne jako pakiet Composer dla TYPO3 v10 do v12. Rozszerzenie jest utrzymywane przez Stefana Froemkena, który również rozwija maps2. Oba rozszerzenia są ze sobą zestrojone, ale mogą być używane niezależnie od siebie.

Gosign standardowo łączy geocoordinates z maps2, by dostarczyć kompletny stos wyszukiwarki oddziałów: wprowadzanie adresu przez redaktora, automatyczne geokodowanie w tle, wyświetlanie mapy z markerem i popupem we frontendzie, wyszukiwanie w okolicy z kodem pocztowym dla odwiedzającego. Stos jest konfigurowany w 2 do 3 dni i pokrywa wymagania 90% wszystkich projektów wyszukiwarek oddziałów.