Migration von Google Geocoding: PHP und Python
Verwenden Sie GoogleGeocodeAdapter für Adresstext und components, lesen Sie geometry.location und lernen Sie die Unterschiede zu Google Geocoding kennen.
Der Adapter unterstützt nur geocode. Er ist kein vollständiger Ersatz für Google Maps, Places oder den Browser-Geocoder und bietet keinen Adapter für umgekehrte Geokodierung. Ersetzen Sie den serverseitigen Aufruf und prüfen Sie die Ergebnisannahmen Ihrer Anwendung.
format=google formatiert die SDK-Ausgabe und ist kein REST-Parameter. ApiClient entfernt ihn vor der HTTP-Anfrage. GoogleGeocodeAdapter wählt ihn automatisch; der dritte Aufruf setzt ihn über extra bei nativer strukturierter Adresseingabe. Der Adapter liefert direkt ein Array/dict; der native SDK-Aufruf liefert ApiResponse. Lesen Sie dessen formatierte Ausgabe mit data().
Die Textanalyse ist best-effort: „Domaniewska 37, Warszawa“ wird in Straße, Hausnummer und Stadt getrennt; „Domaniewska 37“ ohne Komma wird vollständig zu city. Bei Kommas ist der letzte Teil die Stadt, der erste Straße/Hausnummer; mittlere Teile entfallen. Ein angehängtes Land kann somit zur Stadt werden. Nur das polnische Postleitzahlpräfix NN-NNN wird erkannt. Bevorzugen Sie strukturierte Felder oder components. Eine components-Zeichenfolge hat Vorrang vor address, auch wenn sie leer ist; Felder werden nicht zusammengeführt. Unbekannte Komponentennamen werden ignoriert.
language, key, region, result_type und location_type werden entfernt, nicht als Filter oder Spracheinstellungen angewendet. Der Google-Schlüssel authentifiziert nicht bei AutoMapa. Andere Felder auf oberster Ebene können unverändert weitergegeben werden: Senden Sie nur Optionen des AutoMapa-Vertrags.
Der Formatter erzeugt aus den Antwortdaten OK oder ZERO_RESULTS. HTTP-Fehler lösen vor der Formatierung SDK-Ausnahmen aus; erwarten Sie keine Google-Fehlerstatus oder error_message. Status und Fehler sind nicht vollständig Google-kompatibel. place_id und geometry.viewport sind null; location_type wird nicht erzeugt. Prüfen Sie Ihre Anwendung vor dem Anbieterwechsel mit repräsentativen Adressen.
Zuordnung der Eingabe-components
| components | address |
|---|---|
locality | city |
route | street |
street_number | house |
postal_code | pcode |
administrative_area_level_1 | province |
country | country |
sublocality / neighborhood | district |
Zuordnung der Antwortfelder
| AutoMapa / SDK | Ausgabe in Google-Struktur | Bedeutung / Einschränkung |
|---|---|---|
x / y | geometry.location.lng / geometry.location.lat | Längen- / Breitengrad; fehlende Koordinaten bleiben null. |
street, house, pcode, city, country | formatted_address | Lokal aus street, house, pcode, city und country zusammengesetzt. |
country, province, city, district, pcode, street, house | address_components[] | Adressfelder werden typisierte Komponenten; long_name und short_name sind identisch. |
quality | types[] | types wird aus quality abgeleitet: ≤2 country, 3 administrative_area_level_1, 4–5 locality, 6–7 route, ≥8 street_address. Dies ist keine Google-Genauigkeitsklassifikation. |
— | place_id / geometry.viewport | Immer null; weder Google-Kennung noch Gebietsgrenzen werden geliefert. |
raw() | _raw | Die ursprüngliche Antwort bleibt zur Prüfung erhalten; protokollieren Sie keine sensiblen Daten. |
Die festgelegten PHP/Python-geocode-Wrapper senden maxResults auf oberster Ebene (Python-Argument max_results); REST ignoriert es. Der Google-Adapter ergänzt immer maxResults=1 und setzt damit kein Serverlimit. Bekannte Argumente überschreiben extra.address; extra.address.maxResult korrigiert den Wrapper daher nicht. Für ein Limit direkt POST /v3/Geocoder/geocode mit {"address":{"city":"Nowa Wieś","maxResult":3}} aufrufen; bei geocodemulti maxResult in jede Adresse setzen. Native Beispiele lassen die Wrapper-Option weg. Das SDK verlangt city als Argument; der öffentliche REST-Geocoding-Vertrag verlangt city ebenfalls in jeder Adresse. Für polnische Adressen beträgt address.maxResult 1–3 (Standard 1).
Geocoder.geocode · Geocoder.revgeocode
Ergebnisse lesen und Fehler behandeln
Ein leeres Ergebnis oder null wird getrennt von Ausnahmen behandelt. NO_RESULTS ist eine Bezeichnung dieser Beispiele, kein API-Status. Fangen Sie SDK-Ausnahmen bei HTTP-, Transport- oder Dekodierungsfehlern ab; SESSION_REQUIRED verlangt eine neue Sitzung aus Ihrer Integration. Die Kommandozeile meldet einen allgemeinen Fehler, ohne Antwortinhalte oder Sitzungen zu protokollieren. Ergänzen Sie die Fehlerbehandlung Ihrer Anwendung.
PHP benötigt Version 8.0 oder höher, Composer, ext-curl und ext-json. Python benötigt Version 3.11 oder höher und pip. Führen Sie die Befehle für Ihre Sprache im Terminal aus; die Beispiele laufen auf Ihrem Server.
Fixierte Quellstände; die Links zeigen auf die von diesen Beispielen verwendeten Commits.
Speichern Sie die folgenden Bootstrap- und Beispieldateien unter den angegebenen Namen im bei der Installation erstellten SDK-Verzeichnis. Beide Pfade nutzen denselben Bootstrap. Die .txt-Downloads enthalten Quellcode; entfernen Sie .txt beim Speichern.
PHP
automapa-map-services-php81d5014db53d5da37a121d335adc55b4c23c2818
src/Adapter/GoogleGeocodeAdapter.php
1. Festgelegte Quellen installieren
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 mit übergebener Sitzung
Beziehen Sie eine gültige AutoMapa-Sitzung über Ihre serverseitige Authentifizierungsintegration (siehe Authentifizierungsleitfaden) und übergeben Sie sie als AUTOMAPA_SESSION_ID in der Prozessumgebung. Speichern Sie sie nicht im Repository, Browsercode oder in Protokollen. SuppliedSession ist Anwendungscode, der die Speicherschnittstelle des SDK implementiert. Leere Config-Zugangsdaten sind beabsichtigt: get() löst eine Ausnahme aus, wenn die Sitzung fehlt oder nach HTTP 403 gelöscht wurde. So beginnt das SDK keine automatische Anmeldung. Beziehen Sie zum Wiederholen eine neue Sitzung über Ihre Integration und erstellen Sie den Client neu.
bootstrap.php
Quellcode herunterladen — 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. Beispiel ausführen
google-migration.php
Quellcode herunterladen — 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. Festgelegte Quellen installieren
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 mit übergebener Sitzung
Beziehen Sie eine gültige AutoMapa-Sitzung über Ihre serverseitige Authentifizierungsintegration (siehe Authentifizierungsleitfaden) und übergeben Sie sie als AUTOMAPA_SESSION_ID in der Prozessumgebung. Speichern Sie sie nicht im Repository, Browsercode oder in Protokollen. SuppliedSession ist Anwendungscode, der die Speicherschnittstelle des SDK implementiert. Leere Config-Zugangsdaten sind beabsichtigt: get() löst eine Ausnahme aus, wenn die Sitzung fehlt oder nach HTTP 403 gelöscht wurde. So beginnt das SDK keine automatische Anmeldung. Beziehen Sie zum Wiederholen eine neue Sitzung über Ihre Integration und erstellen Sie den Client neu.
bootstrap.py
Quellcode herunterladen — 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. Beispiel ausführen
google-migration.py
Quellcode herunterladen — 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