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

Migracja z Google Geocoding: PHP i Python

Użyj GoogleGeocodeAdapter dla adresu tekstowego i components, odczytaj geometry.location i poznaj różnice względem Google Geocoding.

Adapter obsługuje wyłącznie geocode. Nie jest pełnym zamiennikiem Google Maps, Places ani geokodera przeglądarkowego i nie oferuje adaptera geokodowania odwrotnego. Zastąp wywołanie po stronie serwera i przejrzyj założenia aplikacji dotyczące wyników.

format=google to formatowanie wyniku w SDK, nie parametr REST. ApiClient usuwa go przed wysłaniem HTTP. GoogleGeocodeAdapter wybiera go automatycznie; trzecie wywołanie wybiera go przez extra dla natywnego, strukturalnego adresu wejściowego. Adapter zwraca bezpośrednio tablicę/dict; natywne wywołanie SDK zwraca ApiResponse, więc sformatowany wynik odczytaj przez data().

Parser tekstu działa best-effort: „Domaniewska 37, Warszawa” rozdziela ulicę, numer i miasto, lecz „Domaniewska 37” bez przecinka staje się w całości city. Przy przecinkach ostatnia część oznacza miasto, pierwsza ulicę/numer, a części środkowe są odrzucane. Dopisany kraj może więc zostać miastem. Rozpoznawany jest tylko polski prefiks kodu pocztowego NN-NNN. Preferuj pola strukturalne lub components. Ciąg components ma pierwszeństwo przed address nawet wtedy, gdy jest pusty; pola nie są scalane. Nieznane nazwy komponentów są pomijane.

language, key, region, result_type i location_type są usuwane, nie działają jako filtry ani ustawienia języka. Klucz Google nie uwierzytelnia w AutoMapa. Inne pola najwyższego poziomu mogą być przekazywane bez zmian: wysyłaj tylko opcje obsługiwane przez kontrakt AutoMapa.

Formatter tworzy OK lub ZERO_RESULTS na podstawie danych odpowiedzi. Błędy HTTP powodują wyjątki SDK przed formatowaniem; nie oczekuj statusów błędów Google ani error_message. Statusy i błędy nie są w pełni zgodne z Google. place_id i geometry.viewport są null; location_type nie jest generowane. Przed zmianą dostawcy sprawdź aplikację na reprezentatywnych adresach.

Mapowanie wejściowego components

componentsaddress
localitycity
routestreet
street_numberhouse
postal_codepcode
administrative_area_level_1province
countrycountry
sublocality / neighborhooddistrict

Mapowanie odpowiedzi

AutoMapa / SDKWynik w strukturze GoogleZnaczenie / ograniczenie
x / ygeometry.location.lng / geometry.location.latDługość / szerokość geograficzna; brakujące współrzędne pozostają null.
street, house, pcode, city, countryformatted_addressSkładany lokalnie z street, house, pcode, city i country.
country, province, city, district, pcode, street, houseaddress_components[]Pola adresu stają się komponentami z typami; long_name i short_name mają tę samą wartość.
qualitytypes[]types jest wyznaczane z quality: ≤2 country, 3 administrative_area_level_1, 4–5 locality, 6–7 route, ≥8 street_address. Nie jest to klasyfikacja dokładności Google.
—place_id / geometry.viewportZawsze null; brak identyfikatora Google i granic obszaru.
raw()_rawZachowana oryginalna odpowiedź do analizy; nie loguj danych wrażliwych.

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

src/Adapter/GoogleGeocodeAdapter.php

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

google-migration.php

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

google-migration.py

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