api.automapa.comv3 - alle Systeme normal
Codebeispiele

Natives AutoMapa SDK: PHP und Python

Installieren Sie festgelegte AutoMapa-SDK-Quellen, wandeln Sie Adressen und Koordinaten um und behandeln Sie Ergebnisse und Fehler in PHP und Python.

geocode gibt result als Liste zurück; das Beispiel liest den ersten Treffer und quality. x ist der Längengrad und y der Breitengrad. revgeocode akzeptiert [Längengrad, Breitengrad] und gibt ein Adressobjekt zurück, das keine Koordinaten enthalten muss. pcode kann auch bei Anforderung null sein. raw() erhält den Antwortumschlag; das native data() stellt normalerweise result bereit. Die Beispiele verwenden raw(), um result=null in beiden SDKs gleich zu behandeln. Das Einrasten an einem Gebäude erfolgt nach bestem Bemühen und garantiert keine Hausnummer; Vorwärts- und Rückwärtsgeokodierung müssen keine exakten Umkehrungen sein. Lassen Sie bei internationaler Rückwärtsgeokodierung params weg. Der PHP-SDK-Wrapper sendet es immer; verwenden Sie daher einen direkten REST-Aufruf. Python lässt es ohne Rückwärtsgeokodierungsoptionen weg.

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

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

native.php

Quellcode herunterladen — native.php

<?php
declare(strict_types=1);
require_once __DIR__ . '/bootstrap.php';

use Automapa\MapServices\ApiClient;
use Automapa\MapServices\Exception\AutomapaException;

function geocode(ApiClient $client): array
{
    $response = $client->geocoder()->geocode(
        city: 'Warszawa', street: 'Domaniewska', house: '37', country: 'PL'
    );
    $matches = $response->raw()['result'] ?? [];
    if ($matches === []) {
        return ['status' => 'NO_RESULTS'];
    }
    if (!is_array($matches) || !isset($matches[0])) {
        throw new RuntimeException('UNEXPECTED_RESULT');
    }
    $first = $matches[0];
    return ['status' => 'OK', 'lng' => $first['x'] ?? null, 'lat' => $first['y'] ?? null,
        'city' => $first['city'] ?? null, 'quality' => $first['quality'] ?? null];
}

function revgeocode(ApiClient $client): array
{
    $response = $client->geocoder()->revgeocode(
        point: [21.0065983, 52.1832837], getPostalCode: true
    );
    $address = $response->raw()['result'] ?? [];
    if (!$address) {
        return ['status' => 'NO_RESULTS'];
    }
    if (!is_array($address)) {
        throw new RuntimeException('UNEXPECTED_RESULT');
    }
    return ['status' => 'OK', 'city' => $address['city'] ?? null,
        'street' => $address['street'] ?? null, 'house' => $address['house'] ?? null,
        'pcode' => $address['pcode'] ?? null];
}

if (realpath($_SERVER['SCRIPT_FILENAME'] ?? '') === __FILE__) {
    try {
        $client = buildClient(getenv('AUTOMAPA_SESSION_ID') ?: '');
        echo json_encode(['geocode' => geocode($client), 'revgeocode' => revgeocode($client)]);
    } catch (AutomapaException | RuntimeException $error) {
        fwrite(STDERR, "SDK_ERROR_OR_SESSION_REQUIRED\n");
        exit(1);
    }
}
php native.php

Python

automapa-map-services-python
bdc98c1778d78d11a170b02dd050e89fef9247ba

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

native.py

Quellcode herunterladen — native.py

import json
import os
from bootstrap import build_client
from automapa_map_services.exceptions import AutomapaException


def geocode(client):
    response = client.geocoder().geocode(
        city="Warszawa", street="Domaniewska", house="37", country="PL"
    )
    matches = response.raw().get("result")
    if matches is None or matches == []:
        return {"status": "NO_RESULTS"}
    if not isinstance(matches, list):
        raise RuntimeError("UNEXPECTED_RESULT")
    first = matches[0]
    return {"status": "OK", "lng": first.get("x"), "lat": first.get("y"),
            "city": first.get("city"), "quality": first.get("quality")}


def revgeocode(client):
    response = client.geocoder().revgeocode(
        point=[21.0065983, 52.1832837], get_postal_code=True
    )
    address = response.raw().get("result")
    if not address:
        return {"status": "NO_RESULTS"}
    if not isinstance(address, dict):
        raise RuntimeError("UNEXPECTED_RESULT")
    return {"status": "OK", "city": address.get("city"),
            "street": address.get("street"), "house": address.get("house"),
            "pcode": address.get("pcode")}


if __name__ == "__main__":
    try:
        client = build_client(os.environ.get("AUTOMAPA_SESSION_ID", ""))
        print(json.dumps({"geocode": geocode(client), "revgeocode": revgeocode(client)}))
    except (AutomapaException, RuntimeError):
        raise SystemExit("SDK_ERROR_OR_SESSION_REQUIRED")
python native.py