Нативные 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-php81d5014db53d5da37a121d335adc55b4c23c2818
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-pythonbdc98c1778d78d11a170b02dd050e89fef9247ba
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