SDK AutoMapa natifs : PHP et Python
Installez les sources figées des SDK AutoMapa, convertissez adresses et coordonnées et gérez résultats et erreurs en PHP et Python.
geocode renvoie result sous forme de liste ; l’exemple lit la première correspondance et quality. x est la longitude et y la latitude. revgeocode reçoit [longitude, latitude] et renvoie un objet adresse qui ne contient pas nécessairement de coordonnées. pcode peut être null même s’il est demandé. raw() conserve l’enveloppe de réponse ; data() natif expose normalement result. Les exemples utilisent raw() pour gérer result=null de la même façon dans les deux SDK. L’alignement sur un bâtiment est effectué au mieux et ne garantit pas de numéro ; géocodage direct et inverse ne sont pas nécessairement réciproques. Pour le géocodage inverse international, omettez params. Le wrapper PHP l’envoie toujours ; utilisez donc un appel REST direct. Python l’omet lorsqu’aucune option de géocodage inverse n’est fournie.
Les wrappers geocode PHP/Python figés envoient maxResults à la racine (argument Python max_results), ignoré par REST. L’adaptateur Google ajoute toujours maxResults=1, sans fixer de limite serveur. Les arguments connus écrasent extra.address ; extra.address.maxResult ne corrige donc pas le wrapper. Pour fixer la limite, appeler directement POST /v3/Geocoder/geocode avec {"address":{"city":"Nowa Wieś","maxResult":3}} ; dans geocodemulti, placer maxResult dans chaque adresse. Les exemples natifs omettent cette option du wrapper. Le SDK exige l’argument city ; le contrat public de géocodage REST exige aussi city dans chaque adresse. Pour les adresses polonaises, address.maxResult vaut 1–3 (1 par défaut).
Geocoder.geocode · Geocoder.revgeocode
Lire les résultats et gérer les erreurs
Un résultat vide ou null est traité séparément des exceptions. NO_RESULTS est une étiquette définie par ces exemples, pas un statut API. Interceptez les exceptions SDK pour les erreurs HTTP, de transport ou de décodage ; SESSION_REQUIRED exige une nouvelle session via votre intégration. Les programmes en ligne de commande signalent une erreur générique sans journaliser les réponses ni les sessions. Ajoutez la gestion des erreurs de votre application.
PHP nécessite la version 8.0 ou ultérieure, Composer, ext-curl et ext-json. Python nécessite la version 3.11 ou ultérieure et pip. Exécutez les commandes de votre langage dans un terminal ; les exemples fonctionnent sur votre serveur.
Sources épinglées ; les liens ciblent les commits exacts utilisés par ces exemples.
Enregistrez les fichiers d’amorçage et d’exemple ci-dessous dans le répertoire du SDK créé lors de l’installation, avec les noms indiqués. Les deux parcours utilisent le même amorçage. Les téléchargements .txt contiennent du code source ; retirez .txt lors de l’enregistrement.
PHP
automapa-map-services-php81d5014db53d5da37a121d335adc55b4c23c2818
1. Installer les sources figées
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. Amorçage avec une session fournie
Obtenez une session AutoMapa valide via votre intégration d’authentification côté serveur (voir le guide d’authentification) et transmettez-la dans la variable d’environnement AUTOMAPA_SESSION_ID du processus. Ne la placez pas dans le dépôt, le code du navigateur ou les journaux. SuppliedSession est du code applicatif qui implémente l’interface de stockage du SDK. Les identifiants Config vides sont intentionnels : get() lève une exception si la session manque ou a été effacée après HTTP 403, empêchant la connexion automatique du SDK. Pour réessayer, obtenez une nouvelle session via votre intégration et recréez le client.
bootstrap.php
Télécharger le code source — 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. Exécuter l’exemple
native.php
Télécharger le code source — 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. Installer les sources figées
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. Amorçage avec une session fournie
Obtenez une session AutoMapa valide via votre intégration d’authentification côté serveur (voir le guide d’authentification) et transmettez-la dans la variable d’environnement AUTOMAPA_SESSION_ID du processus. Ne la placez pas dans le dépôt, le code du navigateur ou les journaux. SuppliedSession est du code applicatif qui implémente l’interface de stockage du SDK. Les identifiants Config vides sont intentionnels : get() lève une exception si la session manque ou a été effacée après HTTP 403, empêchant la connexion automatique du SDK. Pour réessayer, obtenez une nouvelle session via votre intégration et recréez le client.
bootstrap.py
Télécharger le code source — 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. Exécuter l’exemple
native.py
Télécharger le code source — 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