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

Нативні SDK AutoMapa: PHP і Python

Встановіть зафіксовані джерела SDK AutoMapa, перетворіть адресу на координати й навпаки та обробіть результати й помилки у PHP і Python.

geocode повертає result як список; приклад читає перший збіг і quality. x — довгота, y — широта. revgeocode приймає [довгота, широта] і повертає об’єкт адреси, який не зобов’язаний містити координати. pcode може бути null навіть якщо його запитано. raw() зберігає оболонку відповіді; нативний data() зазвичай надає result. Приклади використовують raw(), щоб однаково обробляти result=null в обох SDK. Прив’язка до будівлі виконується за можливості та не гарантує номера будинку; пряме й зворотне геокодування не зобов’язані бути точними оберненими операціями. Для міжнародного зворотного геокодування не передавайте params. PHP-обгортка завжди надсилає його, тому використайте прямий REST-запит. Python пропускає його, якщо не задано параметрів зворотного геокодування.

Зафіксовані обгортки 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

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

native.php

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

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

native.py

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