SDK nativos de AutoMapa: PHP y Python
Instala fuentes fijadas de los SDK de AutoMapa, convierte direcciones y coordenadas y gestiona resultados y errores en PHP y Python.
geocode devuelve result como lista; el ejemplo lee la primera coincidencia y quality. x es longitud e y es latitud. revgeocode recibe [longitud, latitud] y devuelve un objeto de dirección que no tiene por qué incluir coordenadas. pcode puede ser null incluso si se solicita. raw() conserva la respuesta completa; data() nativo normalmente expone result. Los ejemplos usan raw() para tratar result=null de forma uniforme en ambos SDK. El ajuste al edificio es de mejor esfuerzo y no garantiza un número; la geocodificación directa e inversa no tienen por qué ser recíprocas exactas. Para la geocodificación inversa internacional, omita params. El wrapper PHP siempre lo envía; use una llamada REST directa. Python lo omite cuando no se indican opciones de geocodificación inversa.
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
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
native.php
Descargar código fuente — 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. 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
native.py
Descargar código fuente — 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