Natywne SDK AutoMapa: PHP i Python
Zainstaluj przypięte źródła SDK AutoMapa, zamień adres na współrzędne i współrzędne na adres oraz obsłuż wyniki i błędy w PHP i Pythonie.
geocode zwraca result jako listę; przykład odczytuje pierwsze dopasowanie i quality. x to długość, a y to szerokość geograficzna. revgeocode przyjmuje [długość, szerokość] i zwraca obiekt adresu, który nie musi zawierać współrzędnych. pcode może być null nawet po jego zażądaniu. raw() zachowuje całą odpowiedź, a natywne data() zwykle udostępnia result. Przykłady używają raw(), aby jednakowo obsłużyć result=null w obu SDK. Przyciąganie do budynku działa best-effort i nie gwarantuje numeru domu; geokodowanie zwykłe i odwrotne nie muszą być dokładnie odwrotne. Przy międzynarodowym geokodowaniu odwrotnym pomiń params. Wrapper PHP zawsze wysyła ten obiekt, dlatego użyj bezpośredniego wywołania REST. Python pomija go, gdy nie podano opcji geokodowania odwrotnego.
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
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
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-pythonbdc98c1778d78d11a170b02dd050e89fef9247ba
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
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