api.automapa.comv3 - усі системи працюють
Приклади коду

Міграція з Google Geocoding: PHP і Python

Використовуйте GoogleGeocodeAdapter для текстових адрес і components, читайте geometry.location та дізнайтеся про відмінності від Google Geocoding.

Адаптер підтримує лише geocode. Він не є повною заміною Google Maps, Places чи браузерного геокодера та не пропонує адаптера зворотного геокодування. Замініть серверний виклик і перегляньте припущення застосунку щодо результатів.

format=google — форматування виходу в SDK, а не параметр REST. ApiClient видаляє його перед HTTP-запитом. GoogleGeocodeAdapter обирає його автоматично; третій виклик задає його через extra для нативної структурованої адреси. Адаптер повертає масив/dict безпосередньо; нативний виклик SDK повертає ApiResponse. Читайте форматований результат через data().

Текстовий парсер працює за принципом best-effort: «Domaniewska 37, Warszawa» розділяє вулицю, номер і місто, але «Domaniewska 37» без коми повністю стає city. За наявності ком остання частина є містом, перша — вулицею/номером, а середні відкидаються. Додана в кінці країна може стати містом. Розпізнається лише польський поштовий префікс NN-NNN. Надавайте перевагу структурованим полям або components. Рядок components має пріоритет над address, навіть порожній; поля не об’єднуються. Невідомі назви компонентів ігноруються.

language, key, region, result_type і location_type видаляються, а не застосовуються як фільтри чи налаштування мови. Ключ Google не автентифікує в AutoMapa. Інші поля верхнього рівня можуть передаватися без змін: надсилайте лише опції контракту AutoMapa.

Форматер створює OK або ZERO_RESULTS з даних відповіді. Помилки HTTP спричиняють винятки SDK до форматування; не очікуйте статусів помилок Google або error_message. Статуси й помилки не повністю сумісні з Google. place_id і geometry.viewport мають значення null; location_type не генерується. Перед зміною постачальника перевірте застосунок на репрезентативних адресах.

Відповідність вхідних components

componentsaddress
localitycity
routestreet
street_numberhouse
postal_codepcode
administrative_area_level_1province
countrycountry
sublocality / neighborhooddistrict

Відповідність полів відповіді

AutoMapa / SDKВихід зі структурою GoogleЗначення / обмеження
x / ygeometry.location.lng / geometry.location.latДовгота / широта; відсутні координати залишаються null.
street, house, pcode, city, countryformatted_addressФормується локально зі street, house, pcode, city і country.
country, province, city, district, pcode, street, houseaddress_components[]Поля адреси стають типізованими компонентами; long_name і short_name мають однакове значення.
qualitytypes[]types визначається за quality: ≤2 country, 3 administrative_area_level_1, 4–5 locality, 6–7 route, ≥8 street_address. Це не класифікація точності Google.
—place_id / geometry.viewportЗавжди null; ідентифікатор Google і межі області не надаються.
raw()_rawПочаткова відповідь збережена для аналізу; не журналюйте чутливі дані.

Зафіксовані обгортки geocode PHP/Python надсилають верхнє maxResults (аргумент Python max_results), яке REST ігнорує. Адаптер Google завжди додає maxResults=1, не задаючи ліміт сервера. Відомі аргументи перезаписують extra.address; extra.address.maxResult не виправляє обгортку. Щоб задати ліміт, виконайте прямий POST /v3/Geocoder/geocode з {"address":{"city":"Nowa Wieś","maxResult":3}}; у geocodemulti задайте maxResult у кожній адресі. Нативні приклади пропускають опцію обгортки. SDK вимагає аргумент city; публічний контракт геокодування REST також вимагає city в кожній адресі. Для польських адрес address.maxResult становить 1–3 (типово 1).

Geocoder.geocode · Geocoder.revgeocode

Читання результатів та обробка помилок

Порожній результат або null обробляється окремо від винятку. NO_RESULTS — позначка цих прикладів, а не статус API. Перехоплюйте винятки SDK для помилок HTTP, транспорту або декодування; SESSION_REQUIRED означає потребу в новій сесії через вашу інтеграцію. Запуск із термінала повідомляє загальну помилку без журналювання відповідей і сесій. Додайте обробку помилок свого застосунку.

PHP потребує версії 8.0 або новішої, Composer, ext-curl та ext-json. Python потребує версії 3.11 або новішої та pip. Виконайте команди для обраної мови в терміналі; приклади працюють на вашому сервері.

Зафіксовані знімки джерел; посилання ведуть на точні коміти, використані цими прикладами.

Збережіть наведені файли початкового налаштування та прикладу в каталозі SDK, створеному під час встановлення, під вказаними назвами. Обидва шляхи використовують те саме налаштування. Завантаження .txt містять вихідний код; видаліть .txt під час збереження.

PHP

automapa-map-services-php
81d5014db53d5da37a121d335adc55b4c23c2818

src/Adapter/GoogleGeocodeAdapter.php

1. Встановіть зафіксовані джерела

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. Початкове налаштування з переданою сесією

Отримайте чинну сесію AutoMapa через власну серверну інтеграцію автентифікації (див. посібник з автентифікації) та передайте її як AUTOMAPA_SESSION_ID в оточенні процесу. Не зберігайте її в репозиторії, коді браузера чи журналах. SuppliedSession нижче — код застосунку, що реалізує інтерфейс зберігання сесій SDK. Порожні облікові дані Config навмисні: get() піднімає виняток, коли сесії немає або її видалено після HTTP 403, запобігаючи автоматичному входу SDK. Для повторної спроби отримайте нову сесію через власну інтеграцію та створіть клієнт знову.

Автентифікація

bootstrap.php

Завантажити код — 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. Запустіть приклад

google-migration.php

Завантажити код — 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. Встановіть зафіксовані джерела

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. Початкове налаштування з переданою сесією

Отримайте чинну сесію AutoMapa через власну серверну інтеграцію автентифікації (див. посібник з автентифікації) та передайте її як AUTOMAPA_SESSION_ID в оточенні процесу. Не зберігайте її в репозиторії, коді браузера чи журналах. SuppliedSession нижче — код застосунку, що реалізує інтерфейс зберігання сесій SDK. Порожні облікові дані Config навмисні: get() піднімає виняток, коли сесії немає або її видалено після HTTP 403, запобігаючи автоматичному входу SDK. Для повторної спроби отримайте нову сесію через власну інтеграцію та створіть клієнт знову.

Автентифікація

bootstrap.py

Завантажити код — 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. Запустіть приклад

google-migration.py

Завантажити код — 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