api.automapa.comv3 - todos los sistemas normales
Ejemplos de código

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

componentsaddress
localitycity
routestreet
street_numberhouse
postal_codepcode
administrative_area_level_1province
countrycountry
sublocality / neighborhooddistrict

Correspondencia de la respuesta

AutoMapa / SDKSalida con estructura GoogleSignificado / limitación
x / ygeometry.location.lng / geometry.location.latLongitud / latitud; las coordenadas ausentes siguen siendo null.
street, house, pcode, city, countryformatted_addressConstruida localmente con street, house, pcode, city y country.
country, province, city, district, pcode, street, houseaddress_components[]Los campos de dirección se convierten en componentes tipados; long_name y short_name usan el mismo valor.
qualitytypes[]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.viewportSiempre null; no se proporcionan identificadores Google ni límites geográficos.
raw()_rawLa 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-php
81d5014db53d5da37a121d335adc55b4c23c2818

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.

Autenticación

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-python
bdc98c1778d78d11a170b02dd050e89fef9247ba

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.

Autenticación

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