Migracja z Google Geocoding: PHP i Python
Użyj GoogleGeocodeAdapter dla adresu tekstowego i components, odczytaj geometry.location i poznaj różnice względem Google Geocoding.
Adapter obsługuje wyłącznie geocode. Nie jest pełnym zamiennikiem Google Maps, Places ani geokodera przeglądarkowego i nie oferuje adaptera geokodowania odwrotnego. Zastąp wywołanie po stronie serwera i przejrzyj założenia aplikacji dotyczące wyników.
format=google to formatowanie wyniku w SDK, nie parametr REST. ApiClient usuwa go przed wysłaniem HTTP. GoogleGeocodeAdapter wybiera go automatycznie; trzecie wywołanie wybiera go przez extra dla natywnego, strukturalnego adresu wejściowego. Adapter zwraca bezpośrednio tablicę/dict; natywne wywołanie SDK zwraca ApiResponse, więc sformatowany wynik odczytaj przez data().
Parser tekstu działa best-effort: „Domaniewska 37, Warszawa” rozdziela ulicę, numer i miasto, lecz „Domaniewska 37” bez przecinka staje się w całości city. Przy przecinkach ostatnia część oznacza miasto, pierwsza ulicę/numer, a części środkowe są odrzucane. Dopisany kraj może więc zostać miastem. Rozpoznawany jest tylko polski prefiks kodu pocztowego NN-NNN. Preferuj pola strukturalne lub components. Ciąg components ma pierwszeństwo przed address nawet wtedy, gdy jest pusty; pola nie są scalane. Nieznane nazwy komponentów są pomijane.
language, key, region, result_type i location_type są usuwane, nie działają jako filtry ani ustawienia języka. Klucz Google nie uwierzytelnia w AutoMapa. Inne pola najwyższego poziomu mogą być przekazywane bez zmian: wysyłaj tylko opcje obsługiwane przez kontrakt AutoMapa.
Formatter tworzy OK lub ZERO_RESULTS na podstawie danych odpowiedzi. Błędy HTTP powodują wyjątki SDK przed formatowaniem; nie oczekuj statusów błędów Google ani error_message. Statusy i błędy nie są w pełni zgodne z Google. place_id i geometry.viewport są null; location_type nie jest generowane. Przed zmianą dostawcy sprawdź aplikację na reprezentatywnych adresach.
Mapowanie wejściowego components
| components | address |
|---|---|
locality | city |
route | street |
street_number | house |
postal_code | pcode |
administrative_area_level_1 | province |
country | country |
sublocality / neighborhood | district |
Mapowanie odpowiedzi
| AutoMapa / SDK | Wynik w strukturze Google | Znaczenie / ograniczenie |
|---|---|---|
x / y | geometry.location.lng / geometry.location.lat | Długość / szerokość geograficzna; brakujące współrzędne pozostają null. |
street, house, pcode, city, country | formatted_address | Składany lokalnie z street, house, pcode, city i country. |
country, province, city, district, pcode, street, house | address_components[] | Pola adresu stają się komponentami z typami; long_name i short_name mają tę samą wartość. |
quality | types[] | types jest wyznaczane z quality: ≤2 country, 3 administrative_area_level_1, 4–5 locality, 6–7 route, ≥8 street_address. Nie jest to klasyfikacja dokładności Google. |
— | place_id / geometry.viewport | Zawsze null; brak identyfikatora Google i granic obszaru. |
raw() | _raw | Zachowana oryginalna odpowiedź do analizy; nie loguj danych wrażliwych. |
Przypięte wrappery geocode PHP/Python wysyłają główne maxResults (argument Pythona: max_results), ignorowane przez REST. Adapter Google zawsze dodaje maxResults=1; nie ustawia tym limitu serwera. Znane argumenty nadpisują extra.address, więc extra.address.maxResult nie naprawia wrappera. Aby ustawić limit, wykonaj bezpośrednie POST /v3/Geocoder/geocode z {"address":{"city":"Nowa Wieś","maxResult":3}}; w geocodemulti umieść maxResult w każdym adresie. Przykłady natywne pomijają opcję wrappera. SDK wymaga argumentu city; publiczny kontrakt geokodowania REST również wymaga city w każdym adresie. Dla adresów w Polsce address.maxResult wynosi 1–3 (domyślnie 1).
Geocoder.geocode · Geocoder.revgeocode
Odczyt wyników i obsługa błędów
Pusty wynik lub null jest obsługiwany oddzielnie od wyjątku. NO_RESULTS to etykieta zdefiniowana w przykładach, nie status API. Przechwytuj wyjątki SDK dla błędów HTTP, transportu i dekodowania; SESSION_REQUIRED oznacza konieczność przekazania świeżej sesji przez własną integrację. Uruchomienie z terminala zgłasza ogólny błąd bez logowania treści odpowiedzi i sesji. Przed integracją dodaj obsługę błędów właściwą dla swojej aplikacji.
PHP wymaga wersji 8.0 lub nowszej, Composera, ext-curl i ext-json. Python wymaga wersji 3.11 lub nowszej oraz pip. Wykonaj polecenia dla wybranego języka w terminalu; przykłady działają na Twoim serwerze.
Przypięte migawki źródeł; linki prowadzą do dokładnych commitów użytych w tych przykładach.
Zapisz poniższe pliki bootstrapu i przykładu w katalogu repozytorium SDK utworzonym podczas instalacji, pod wskazanymi nazwami. Obie ścieżki korzystają z tego samego bootstrapu. Pliki do pobrania .txt zawierają kod źródłowy; usuń .txt przy zapisie.
PHP
automapa-map-services-php81d5014db53d5da37a121d335adc55b4c23c2818
src/Adapter/GoogleGeocodeAdapter.php
1. Zainstaluj przypięte źródła
git clone https://github.com/automapa/automapa-map-services-php.git
cd automapa-map-services-php
git checkout --detach 81d5014db53d5da37a121d335adc55b4c23c2818
composer install --no-dev
2. Bootstrap z przekazaną sesją
Uzyskaj ważną sesję AutoMapa przez własną integrację uwierzytelniania po stronie serwera (zobacz przewodnik uwierzytelniania) i przekaż ją jako AUTOMAPA_SESSION_ID w środowisku procesu. Nie umieszczaj jej w repozytorium, kodzie przeglądarki ani logach. Poniższa klasa SuppliedSession to kod aplikacji implementujący interfejs przechowywania sesji SDK. Puste poświadczenia Config są celowe: get() rzuca wyjątek, gdy sesji brak lub została usunięta po HTTP 403, zapobiegając automatycznemu logowaniu SDK. Aby ponowić próbę, uzyskaj nową sesję przez własną integrację i utwórz klienta ponownie.
bootstrap.php
Pobierz źródło — bootstrap.php
<?php
declare(strict_types=1);
require_once __DIR__ . '/vendor/autoload.php';
use Automapa\MapServices\ApiClient;
use Automapa\MapServices\Config;
use Automapa\MapServices\Http\CurlHttpClient;
use Automapa\MapServices\Http\HttpClientInterface;
use Automapa\MapServices\Session\SessionManager;
use Automapa\MapServices\Session\SessionStorage;
final class SuppliedSession implements SessionStorage
{
public function __construct(private string $sessionId) {}
public function get(): ?string
{
if ($this->sessionId === '') {
throw new RuntimeException('SESSION_REQUIRED');
}
return $this->sessionId;
}
public function store(string $sessionId): void
{
$this->sessionId = $sessionId;
}
public function clear(): void
{
$this->sessionId = '';
}
}
function buildClient(string $sessionId, ?HttpClientInterface $http = null): ApiClient
{
$storage = new SuppliedSession($sessionId);
$storage->get();
$config = new Config(key: '', pass: '', baseUrl: 'https://api.automapa.com/');
$http ??= new CurlHttpClient();
return new ApiClient($config, $http, new SessionManager($config, $http, $storage));
}
3. Uruchom przykład
google-migration.php
Pobierz źródło — google-migration.php
<?php
declare(strict_types=1);
require_once __DIR__ . '/bootstrap.php';
use Automapa\MapServices\ApiClient;
use Automapa\MapServices\Adapter\GoogleGeocodeAdapter;
use Automapa\MapServices\Exception\AutomapaException;
function readLocation(array $data): array
{
if (($data['status'] ?? '') === 'ZERO_RESULTS') {
return ['status' => 'NO_RESULTS'];
}
if (($data['status'] ?? '') !== 'OK') {
throw new RuntimeException('UNEXPECTED_STATUS');
}
if (empty($data['results'])) {
return ['status' => 'NO_RESULTS'];
}
$first = $data['results'][0];
$location = $first['geometry']['location'];
return ['status' => 'OK', 'lat' => $location['lat'], 'lng' => $location['lng'],
'address' => $first['formatted_address']];
}
function migrate(ApiClient $client): array
{
$adapter = new GoogleGeocodeAdapter($client);
$text = $adapter->geocode(['address' => 'Domaniewska 37, Warszawa']);
$components = $adapter->geocode([
'components' => 'locality:Warszawa|route:Domaniewska|street_number:37|country:PL',
]);
$nativeInput = $client->geocoder()->geocode(
city: 'Warszawa', street: 'Domaniewska', house: '37', country: 'PL',
extra: ['format' => 'google'],
)->data();
return array_map('readLocation', [$text, $components, $nativeInput]);
}
if (realpath($_SERVER['SCRIPT_FILENAME'] ?? '') === __FILE__) {
try {
$client = buildClient(getenv('AUTOMAPA_SESSION_ID') ?: '');
echo json_encode(migrate($client));
} catch (AutomapaException | RuntimeException | InvalidArgumentException $error) {
fwrite(STDERR, "SDK_ERROR_OR_SESSION_REQUIRED\n");
exit(1);
}
}
php google-migration.php
Python
automapa-map-services-pythonbdc98c1778d78d11a170b02dd050e89fef9247ba
automapa_map_services/adapter/google_geocode.py
1. Zainstaluj przypięte źródła
git clone https://github.com/automapa/automapa-map-services-python.git
cd automapa-map-services-python
git checkout --detach bdc98c1778d78d11a170b02dd050e89fef9247ba
python3 -m venv .venv
. .venv/bin/activate
python -m pip install .
2. Bootstrap z przekazaną sesją
Uzyskaj ważną sesję AutoMapa przez własną integrację uwierzytelniania po stronie serwera (zobacz przewodnik uwierzytelniania) i przekaż ją jako AUTOMAPA_SESSION_ID w środowisku procesu. Nie umieszczaj jej w repozytorium, kodzie przeglądarki ani logach. Poniższa klasa SuppliedSession to kod aplikacji implementujący interfejs przechowywania sesji SDK. Puste poświadczenia Config są celowe: get() rzuca wyjątek, gdy sesji brak lub została usunięta po HTTP 403, zapobiegając automatycznemu logowaniu SDK. Aby ponowić próbę, uzyskaj nową sesję przez własną integrację i utwórz klienta ponownie.
bootstrap.py
from automapa_map_services.client import ApiClient
from automapa_map_services.config import Config
from automapa_map_services.http.urllib_client import UrllibHttpClient
from automapa_map_services.session.manager import SessionManager
class SuppliedSession:
def __init__(self, session_id: str):
self.session_id = session_id
def get(self) -> str:
if not self.session_id:
raise RuntimeError("SESSION_REQUIRED")
return self.session_id
def store(self, session_id: str) -> None:
self.session_id = session_id
def clear(self) -> None:
self.session_id = ""
def build_client(session_id: str, http_client=None) -> ApiClient:
storage = SuppliedSession(session_id)
storage.get()
config = Config(key="", password="", base_url="https://api.automapa.com/")
http = http_client if http_client is not None else UrllibHttpClient()
return ApiClient(config, http, SessionManager(config, http, storage))
3. Uruchom przykład
google-migration.py
Pobierz źródło — google-migration.py
import json
import os
from bootstrap import build_client
from automapa_map_services.adapter.google_geocode import GoogleGeocodeAdapter
from automapa_map_services.exceptions import AutomapaException
def read_location(data):
if data.get("status") == "ZERO_RESULTS":
return {"status": "NO_RESULTS"}
if data.get("status") != "OK":
raise RuntimeError("UNEXPECTED_STATUS")
if not data.get("results"):
return {"status": "NO_RESULTS"}
first = data["results"][0]
location = first["geometry"]["location"]
return {"status": "OK", "lat": location["lat"], "lng": location["lng"],
"address": first["formatted_address"]}
def migrate(client):
adapter = GoogleGeocodeAdapter(client)
text = adapter.geocode({"address": "Domaniewska 37, Warszawa"})
components = adapter.geocode({
"components": "locality:Warszawa|route:Domaniewska|street_number:37|country:PL"
})
native_input = client.geocoder().geocode(
city="Warszawa", street="Domaniewska", house="37", country="PL",
extra={"format": "google"},
).data()
return [read_location(data) for data in (text, components, native_input)]
if __name__ == "__main__":
try:
client = build_client(os.environ.get("AUTOMAPA_SESSION_ID", ""))
print(json.dumps(migrate(client)))
except (AutomapaException, RuntimeError, ValueError):
raise SystemExit("SDK_ERROR_OR_SESSION_REQUIRED")
python google-migration.py