api.automapa.comv3 - alle Systeme normal
Codebeispiele

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

componentsaddress
localitycity
routestreet
street_numberhouse
postal_codepcode
administrative_area_level_1province
countrycountry
sublocality / neighborhooddistrict

Zuordnung der Antwortfelder

AutoMapa / SDKAusgabe in Google-StrukturBedeutung / Einschränkung
x / ygeometry.location.lng / geometry.location.latLängen- / Breitengrad; fehlende Koordinaten bleiben null.
street, house, pcode, city, countryformatted_addressLokal aus street, house, pcode, city und country zusammengesetzt.
country, province, city, district, pcode, street, houseaddress_components[]Adressfelder werden typisierte Komponenten; long_name und short_name sind identisch.
qualitytypes[]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.viewportImmer null; weder Google-Kennung noch Gebietsgrenzen werden geliefert.
raw()_rawDie 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-php
81d5014db53d5da37a121d335adc55b4c23c2818

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.

Authentifizierung

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-python
bdc98c1778d78d11a170b02dd050e89fef9247ba

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.

Authentifizierung

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