Migración desde Google Geocoding: PHP y Python
Usa GoogleGeocodeAdapter con direcciones de texto y components, lee geometry.location y conoce las diferencias con Google Geocoding.
Este adaptador solo admite geocode. No sustituye por completo a Google Maps, Places ni al geocodificador del navegador, y no ofrece un adaptador de geocodificación inversa. Sustituye la llamada del servidor y revisa las suposiciones de tu aplicación sobre los resultados.
format=google es un formateador de salida del SDK, no un parámetro REST. ApiClient lo elimina antes del envío HTTP. GoogleGeocodeAdapter lo selecciona automáticamente; la tercera llamada lo elige mediante extra con una dirección estructurada nativa. El adaptador devuelve un array/dict directamente; una llamada nativa del SDK devuelve ApiResponse. Usa data() para leer su salida formateada.
El análisis del texto es aproximado (best-effort): «Domaniewska 37, Warszawa» separa calle, número y ciudad, pero «Domaniewska 37» sin coma se convierte íntegramente en city. Con comas, la última parte es la ciudad, la primera calle/número y las intermedias se descartan. Un país añadido al final puede convertirse en la ciudad. Solo se reconoce el prefijo postal polaco NN-NNN. Prefiere campos estructurados o components. Una cadena components tiene prioridad sobre address incluso vacía; los campos no se combinan. Se ignoran los nombres de componentes desconocidos.
language, key, region, result_type y location_type se eliminan, sin aplicarse como filtros o ajustes de idioma. La clave Google no autentica en AutoMapa. Otros campos de primer nivel pueden reenviarse sin cambios: envía solo opciones del contrato AutoMapa.
El formateador crea OK o ZERO_RESULTS a partir de los datos de respuesta. Los fallos HTTP lanzan excepciones del SDK antes del formateo; no esperes estados de error Google ni error_message. Los estados y errores no son totalmente compatibles con Google. place_id y geometry.viewport son null; no se genera location_type. Prueba tu aplicación con direcciones representativas antes de cambiar de proveedor.
Correspondencia de components de entrada
| components | address |
|---|---|
locality | city |
route | street |
street_number | house |
postal_code | pcode |
administrative_area_level_1 | province |
country | country |
sublocality / neighborhood | district |
Correspondencia de la respuesta
| AutoMapa / SDK | Salida con estructura Google | Significado / limitación |
|---|---|---|
x / y | geometry.location.lng / geometry.location.lat | Longitud / latitud; las coordenadas ausentes siguen siendo null. |
street, house, pcode, city, country | formatted_address | Construida localmente con street, house, pcode, city y country. |
country, province, city, district, pcode, street, house | address_components[] | Los campos de dirección se convierten en componentes tipados; long_name y short_name usan el mismo valor. |
quality | types[] | types se deduce de quality: ≤2 country, 3 administrative_area_level_1, 4–5 locality, 6–7 route, ≥8 street_address. No es la clasificación de precisión de Google. |
— | place_id / geometry.viewport | Siempre null; no se proporcionan identificadores Google ni límites geográficos. |
raw() | _raw | La respuesta original se conserva para inspección; no registres datos sensibles. |
Los wrappers geocode PHP/Python fijados envían maxResults en la raíz (argumento Python max_results), ignorado por REST. El adaptador Google siempre añade maxResults=1, sin fijar un límite del servidor. Los argumentos conocidos sobrescriben extra.address; extra.address.maxResult no corrige el wrapper. Para fijar el límite, llamar directamente a POST /v3/Geocoder/geocode con {"address":{"city":"Nowa Wieś","maxResult":3}}; en geocodemulti, incluir maxResult en cada dirección. Los ejemplos nativos omiten la opción del wrapper. El SDK exige city como argumento; el contrato público de geocodificación REST también exige city en cada dirección. Para direcciones polacas, address.maxResult es 1–3 (1 por defecto).
Geocoder.geocode · Geocoder.revgeocode
Leer resultados y gestionar errores
Un resultado vacío o null se gestiona por separado de las excepciones. NO_RESULTS es una etiqueta de estos ejemplos, no un estado de la API. Captura excepciones del SDK para fallos HTTP, de transporte o decodificación; SESSION_REQUIRED exige una sesión nueva de tu integración. Los programas de terminal indican un error genérico sin registrar respuestas ni sesiones. Añade la gestión de errores de tu aplicación.
PHP requiere la versión 8.0 o posterior, Composer, ext-curl y ext-json. Python requiere la versión 3.11 o posterior y pip. Ejecuta los comandos de tu lenguaje en una terminal; los ejemplos se ejecutan en tu servidor.
Fuentes fijadas; los enlaces apuntan a los commits exactos usados por estos ejemplos.
Guarda los archivos de inicialización y ejemplo siguientes en el directorio del SDK creado durante la instalación, con los nombres indicados. Ambas rutas usan la misma inicialización. Las descargas .txt contienen código fuente; elimina .txt al guardar.
PHP
automapa-map-services-php81d5014db53d5da37a121d335adc55b4c23c2818
src/Adapter/GoogleGeocodeAdapter.php
1. Instala las fuentes fijadas
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. Inicializa con una sesión proporcionada
Obtén una sesión válida de AutoMapa mediante tu integración de autenticación del servidor (consulta la guía de autenticación) y pásala como AUTOMAPA_SESSION_ID en el entorno del proceso. No la incluyas en el repositorio, código del navegador ni registros. SuppliedSession es código de aplicación que implementa la interfaz de almacenamiento del SDK. Las credenciales Config vacías son intencionadas: get() lanza una excepción si falta la sesión o se ha borrado tras HTTP 403, evitando el inicio de sesión automático del SDK. Para reintentar, obtén una sesión nueva mediante tu integración y vuelve a crear el cliente.
bootstrap.php
Descargar código fuente — 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. Ejecuta el ejemplo
google-migration.php
Descargar código fuente — 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. Instala las fuentes fijadas
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. Inicializa con una sesión proporcionada
Obtén una sesión válida de AutoMapa mediante tu integración de autenticación del servidor (consulta la guía de autenticación) y pásala como AUTOMAPA_SESSION_ID en el entorno del proceso. No la incluyas en el repositorio, código del navegador ni registros. SuppliedSession es código de aplicación que implementa la interfaz de almacenamiento del SDK. Las credenciales Config vacías son intencionadas: get() lanza una excepción si falta la sesión o se ha borrado tras HTTP 403, evitando el inicio de sesión automático del SDK. Para reintentar, obtén una sesión nueva mediante tu integración y vuelve a crear el cliente.
bootstrap.py
Descargar código fuente — 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. Ejecuta el ejemplo
google-migration.py
Descargar código fuente — 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