Миграция с 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
| components | address |
|---|---|
locality | city |
route | street |
street_number | house |
postal_code | pcode |
administrative_area_level_1 | province |
country | country |
sublocality / neighborhood | district |
Соответствие полей ответа
| AutoMapa / SDK | Вывод со структурой Google | Значение / ограничение |
|---|---|---|
x / y | geometry.location.lng / geometry.location.lat | Долгота / широта; отсутствующие координаты остаются null. |
street, house, pcode, city, country | formatted_address | Формируется локально из street, house, pcode, city и country. |
country, province, city, district, pcode, street, house | address_components[] | Поля адреса становятся типизированными компонентами; long_name и short_name имеют одинаковое значение. |
quality | types[] | 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-php81d5014db53d5da37a121d335adc55b4c23c2818
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-pythonbdc98c1778d78d11a170b02dd050e89fef9247ba
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