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