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