Compatibilidad drop-in

No tienes que aprender esta API para usarla. Para otras diecisiete API de geocodificación y consulta de IP tenemos un host que acepta el formato de solicitud de ese proveedor y responde en su formato de respuesta, con nuestros datos detrás. Lo mismo se aplica a las bibliotecas de mapas en JavaScript que ofrecen esos proveedores. Migrar es cambiar un nombre de host.

Cómo funciona

Cada host compatible es una implementación completa de la interfaz HTTP pública de un proveedor: las mismas rutas, los mismos parámetros de consulta, los mismos nombres de campos JSON, anidamiento y tipos, el mismo vocabulario de estados y las mismas estructuras de error. Los valores son nuestros. Tu código cliente, tu código de análisis y tu gestión de errores no cambian.

1. Cambia el host. maps.googleapis.com pasa a ser gapi.mygeocode.com, dev.virtualearth.net pasa a ser bing.mygeocode.com, y así sucesivamente. La tabla de abajo tiene todos los pares.
2. Cambia la clave o quítala. Pon tu clave de My Geocode en el parámetro que usaba la clave anterior (key, apiKey, access_token, token...). Cualquier dirección tiene 2.500 solicitudes gratuitas al día sin clave, y cada clave trae 2.500 propias, así que migrar y hacer pruebas no cuesta nada.
3. Compara. Ejecuta una muestra de solicitudes reales contra ambos hosts. Las coordenadas diferirán ligeramente porque los datos son distintos; los nombres de los campos no.

$ curl "https://maps.googleapis.com/maps/api/geocode/json?address=10+Downing+St+London&key=GOOGLE_KEY"

$ curl "https://gapi.mygeocode.com/maps/api/geocode/json?address=10+Downing+St+London&key=MYGEOCODE_KEY"

Todos los hosts compatibles

Todos los hosts funcionan sobre la misma infraestructura, con los mismos datos, la misma cuota gratuita y los mismos precios que api.mygeocode.com. Haz clic en un proveedor para ver su lista de endpoints, una respuesta de ejemplo y las diferencias conocidas.

Bibliotecas de mapas en JavaScript

Los cambios de proveedor duelen más en el navegador, donde el mapa, el widget de geocodificación y la facturación están enredados. En las bibliotecas de abajo, la propia biblioteca se carga desde nuestro host (o, en el caso de MapLibre, Mapbox GL y Leaflet, se apunta a nuestro host mediante configuración) y conserva su API pública: google.maps.Map, Microsoft.Maps.Map, H.Map y el resto. Las teselas, la geocodificación, el autocompletado y la elevación los ponemos nosotros. Las cargas de mapas y las teselas son gratuitas; las llamadas de geocodificación cuentan como siempre.

La página de reemplazos compatibles en JavaScript tiene los fragmentos de antes y después, la lista de lo que incluye y no incluye cada biblioteca, y las URL de teselas y estilos.

Dónde va la clave

Cada host acepta la clave en el lugar donde la espera el proveedor original, y también en la cabecera X-API-Key. La clave es opcional: 2.500 solicitudes al día por dirección no la necesitan. Una clave gratuita se obtiene en un minuto y añade crédito, paquetes y un historial de uso. Una clave de pago por uso puede usarse desde dos direcciones IP por cada 24 horas móviles y una clave Unlimited desde tres; usa más claves o paquetes para más direcciones (consulta autenticación).

Cuota y errores en los hosts compatibles

La cuota diaria es la misma que en todas partes y se cuenta por clave, o por dirección si no se envía clave, entre api.mygeocode.com y todos los hosts compatibles: 2.500 gratuitas al día y después crédito o una clave Unlimited. Las cabeceras X-Quota-* y X-Key-IPs-* se envían en todos los hosts, así que puedes leer el estado real en las cabeceras sea cual sea el formato del cuerpo. En el cuerpo, los límites se informan como los informa el proveedor:

Qué coincide y qué no

Lista de comprobación para la migración

1. Busca el nombre de host del proveedor en tu código y tu configuración. Suele estar en más de un sitio: código del servidor, apps móviles, una regla de CDN, una configuración en caché.
2. Cámbialo por el host compatible de la tabla anterior. Conserva la ruta.
3. Sustituye la clave por una clave de My Geocode. Usa una clave por servidor, o dos como máximo; una clave de pago por uso acepta dos direcciones IP por cada 24 horas móviles, una clave Unlimited tres.
4. Ejecuta tu batería de pruebas actual. Debería pasar sin cambios. Si falta un campo del que dependes, revisa en la página del host las carencias conocidas y avísanos.
5. Repite unos cientos de solicitudes reales contra ambos hosts y compara las coordenadas y los campos que muestras. Fíjate en precision donde el host compatible la expone (como location_type, accuracy, resultType, etc.).
6. Observa X-Quota-Used durante un día para dimensionar tu plan: crédito por debajo de unas 19.000 solicitudes al día, una clave Unlimited por encima.
7. Cancela la facturación anterior.

SDK de los proveedores

La mayoría de las bibliotecas cliente oficiales aceptan una URL base personalizada, así que también funcionan con los hosts compatibles: los clientes de Google Maps Services (googlemaps para Python, @googlemaps/google-maps-services-js), los SDK de Mapbox (opción origin), los clientes REST de HERE, las bibliotecas de ipinfo y los wrappers de Nominatim como geopy (domain=). Apúntalos al host de la tabla y pasa tu clave de My Geocode donde iba la clave del proveedor.

Un proveedor que no aparece en la lista

Añadir un host lleva unos días de trabajo cuando el formato del proveedor está documentado. Si usas un servicio que no está aquí, dinos cuál y aproximadamente cuántas solicitudes envías al día. Todas las incorporaciones recientes fueron peticiones de usuarios.