Migration depuis Google Geocoding : PHP et Python
Utilisez GoogleGeocodeAdapter pour les adresses textuelles et components, lisez geometry.location et découvrez les différences avec Google Geocoding.
Cet adaptateur gère uniquement geocode. Il ne remplace pas intégralement Google Maps, Places ou le géocodeur du navigateur et ne fournit pas d’adaptateur de géocodage inverse. Remplacez l’appel côté serveur et examinez les hypothèses de votre application concernant les résultats.
format=google est un formateur de sortie du SDK, pas un paramètre REST. ApiClient le retire avant l’envoi HTTP. GoogleGeocodeAdapter le sélectionne automatiquement ; le troisième appel le choisit via extra avec une adresse structurée native. L’adaptateur renvoie directement un tableau/dict ; un appel SDK natif renvoie ApiResponse. Utilisez data() pour lire sa sortie formatée.
L’analyse du texte est approximative (best-effort) : « Domaniewska 37, Warszawa » sépare rue, numéro et ville, mais « Domaniewska 37 » sans virgule devient entièrement city. Avec des virgules, le dernier élément est la ville, le premier la rue/le numéro ; les éléments intermédiaires sont supprimés. Un pays ajouté à la fin peut donc devenir la ville. Seul le préfixe postal polonais NN-NNN est reconnu. Préférez des champs structurés ou components. Une chaîne components prime sur address, même vide ; les champs ne sont pas fusionnés. Les noms de composants inconnus sont ignorés.
language, key, region, result_type et location_type sont supprimés, sans appliquer de filtre ni de langue. La clé Google n’authentifie pas auprès d’AutoMapa. Les autres champs de premier niveau peuvent être transmis tels quels : envoyez uniquement les options du contrat AutoMapa.
Le formateur crée OK ou ZERO_RESULTS à partir des données de réponse. Les erreurs HTTP lèvent des exceptions SDK avant le formatage ; n’attendez pas les statuts d’erreur Google ni error_message. Les statuts et erreurs ne sont pas entièrement compatibles avec Google. place_id et geometry.viewport sont null ; location_type n’est pas généré. Testez votre application sur des adresses représentatives avant de changer de fournisseur.
Correspondance des components en entrée
| components | address |
|---|---|
locality | city |
route | street |
street_number | house |
postal_code | pcode |
administrative_area_level_1 | province |
country | country |
sublocality / neighborhood | district |
Correspondance des champs de réponse
| AutoMapa / SDK | Sortie de structure Google | Sens / limite |
|---|---|---|
x / y | geometry.location.lng / geometry.location.lat | Longitude / latitude ; les coordonnées absentes restent null. |
street, house, pcode, city, country | formatted_address | Construit localement à partir de street, house, pcode, city et country. |
country, province, city, district, pcode, street, house | address_components[] | Les champs d’adresse deviennent des composants typés ; long_name et short_name ont la même valeur. |
quality | types[] | types est déduit de quality : ≤2 country, 3 administrative_area_level_1, 4–5 locality, 6–7 route, ≥8 street_address. Ce n’est pas la classification de précision de Google. |
— | place_id / geometry.viewport | Toujours null ; aucun identifiant Google ni limites géographiques fournis. |
raw() | _raw | L’enveloppe de réponse originale est conservée pour analyse ; ne journalisez pas de données sensibles. |
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
src/Adapter/GoogleGeocodeAdapter.php
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
google-migration.php
Télécharger le code source — 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. 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
google-migration.py
Télécharger le code source — 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