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. Rozszerzenie geocodingowe, takie jak maps2, rozwiązuje ten problem automatycznie: 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. maps2 podłącza tabelę tt_address przez swój rejestr i reaguje na każdy zapis przez DataHandler-Hook. Gdy redaktor zmieni adres lub utworzy nową lokalizację, w tle wywoływany jest serwis geocodingowy. maps2 zapisuje współrzędne we własnym rekordzie lokalizacji powiązanym z adresem i na jego podstawie 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. tt_address ma komendę CLI ttaddress:geocode, która geokoduje wszystkie rekordy bez współrzędnych w jednym przebiegu batchowym przez Google Geocoding API.

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, serwis geocodingowy 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

maps2 integruje się jako DataHandler-Hook w TYPO3 Core. Rozszerzenie monitoruje tabele i pola adresowe podłączone przez TCA do jego rejestru. Gdy monitorowane pole adresowe się zmieni, maps2 przy zapisie wyzwala żą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).

maps2 przechowuje współrzędne we własnym rekordzie lokalizacji w polach latitude i longitude, a tt_address w polach dziesiętnych o tej samej nazwie. Dla wyszukiwania w okolicy maps2 oblicza odległość formułą SQL w QueryBuilder; funkcję Haversine można też wbudować we własne 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. maps2 przekazuje adres do serwisu w kodowaniu URL, 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: utrzymanie przebiegu batchowego poniżej limitu 3000 żądań na minutę.

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

Rozszerzenie o nazwie geocoordinates nie jest opublikowane ani w TER, ani na Packagist. maps2 Stefana Froemkena (jweiland.net) ma wbudowany geocoding, obecnie 13.1.0 dla TYPO3 v14 i 12.2.0 dla v13. tt_address ma własną komendę geocodingu ttaddress:geocode; oba rozszerzenia 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.