api.automapa.comv3 - wszystkie systemy działają
Przykłady kodu

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-php
81d5014db53d5da37a121d335adc55b4c23c2818

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.

Uwierzytelnianie

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

Pobierz źródło — 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. 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.

Uwierzytelnianie

bootstrap.py

Pobierz źródło — 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

Pobierz źródło — 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