Autenticación

Las primeras 2.500 solicitudes al día desde una dirección no necesitan clave. La clave sirve para todo lo que venga después: decide de qué crédito o paquete se descuenta una solicitud y qué máquinas pueden usarla, y te da un historial de uso. Las claves son gratuitas y se obtienen en un minuto.

Sin clave

Envía la solicitud sin ninguna credencial y se responde. Cada dirección tiene 2.500 solicitudes al día de esta forma, contadas desde las 00:00 UTC en todos los endpoints y todos los hosts compatibles, con los mismos datos y las mismas respuestas que una cuenta de pago. A partir de ahí, la API responde 429 quota_exceeded con una cabecera Retry-After hasta el reinicio; no se cobra nada y nada queda en cola.

Dos cosas que debes saber. Las direcciones que pertenecen a la misma red comparten una sola cuota, así que una oficina con mucho tráfico, un campus o una región de nube pueden agotarla más rápido que una sola máquina. Y una red y las claves que se usan desde ella comparten la misma cuota: las solicitudes hechas sin clave reducen lo que obtiene hoy una clave usada desde esa red, y las solicitudes gratuitas hechas con esa clave reducen lo que obtiene la red sin clave. Por eso, registrarte añade crédito, paquetes e historial, no unas segundas 2.500 gratuitas desde el mismo lugar.

Cómo obtener una clave

Regístrate en www.mygeocode.com/signup con tu nombre, una dirección de correo electrónico y una contraseña. Tu primera clave se muestra una sola vez, en el momento; cópiala, porque solo se guarda un hash. Crea tantas claves adicionales como quieras en Claves de API, ponle una etiqueta a cada una (una por servidor o por aplicación es un buen hábito) y revoca cualquiera de ellas en cualquier momento.

Cada clave tiene 2.500 solicitudes gratuitas al día, contadas desde las 00:00 UTC en todos los endpoints y todos los hosts compatibles. A partir de ahí, las solicitudes se descuentan del crédito prepago de la cuenta a 0,0001 € cada una, salvo que la clave pertenezca a un paquete Unlimited.

Cómo enviar la clave

Cualquiera de estas opciones funciona en todos los hosts. Es preferible la cabecera: las cadenas de consulta acaban en los registros del servidor, el historial del navegador y los proxies.

$ curl -H "X-API-Key: mg_7f3c2a19e04b...d1" "https://api.mygeocode.com/v1/reverse?lat=51.5&lon=-0.12"

$ curl -H "Authorization: Bearer mg_7f3c2a19e04b...d1" "https://api.mygeocode.com/v1/reverse?lat=51.5&lon=-0.12"

$ curl "https://api.mygeocode.com/v1/reverse?lat=51.5&lon=-0.12&key=mg_7f3c2a19e04b...d1"

$ curl -u "mg_7f3c2a19e04b...d1:" "https://api.mygeocode.com/v1/reverse?lat=51.5&lon=-0.12"

En los hosts compatibles, la clave también va donde iba la clave del proveedor original: key para Google, Bing, Geocode.Farm, OpenCage, LocationIQ, TomTom y MapQuest; apiKey para HERE y Geoapify; access_token para Mapbox; api_key para Geocodio; access_key para PositionStack e ipstack; token para ipinfo. Los clientes de Nominatim y Open-Elevation añaden key= o una cabecera, ya que esos dos servicios no tienen clave propia.

Además del parámetro de consulta, se aceptan cuatro formas de enviar credenciales en todos los hosts, así que una biblioteca cliente que se autentica a la manera del proveedor no necesita cambios: la cabecera X-API-Key, Authorization: Bearer, la autenticación HTTP Basic con la clave como nombre de usuario (lo que envía curl -u KEY: y lo que usan los ejemplos de ipinfo) y la cabecera X-Goog-Api-Key que envían los clientes de Google. También se lee una clave en el cuerpo de un formulario, para los endpoints que reciben POST. Cambiar el nombre de host y la clave es toda la migración.

Dos tipos de clave

Espacios de IP

Una clave puede usarse desde un número limitado de direcciones IP a la vez: dos para una clave de pago por uso, tres para una clave Unlimited. La regla es móvil, por dirección:

• La primera vez que una dirección usa la clave, ocupa un espacio y lo mantiene durante 24 horas desde esa primera solicitud.
• Cuando pasan esas 24 horas, el espacio se libera solo, hagan lo que hagan las demás direcciones. Si la misma dirección vuelve más tarde, simplemente ocupa un espacio de nuevo.
• Una solicitud desde una dirección nueva mientras todos los espacios están ocupados se rechaza con 403 y el código key_ip_limit. El mensaje indica cuándo se libera el siguiente espacio. Las solicitudes rechazadas no se contabilizan.

Así, si dos servidores usaron una clave por primera vez a las 02:00 y un tercero a las 04:00, dos espacios se liberan a las 02:00 del día siguiente y el tercero a las 04:00. El panel muestra qué direcciones ocupan los espacios de una clave y cuándo se libera cada uno. ¿Necesitas más máquinas? Crea más claves de pago por uso o añade más paquetes Unlimited; cada paquete trae su propia clave.

El límite existe porque las claves se filtran. Con él, una clave que acaba en un repositorio público vale muy poco para quien la encuentre, y como el crédito es prepago, nadie puede gastar más que el saldo que cargaste.

Claves y navegadores

No pongas una clave en JavaScript ni en una app móvil. Cualquiera puede leerla en la página, y cada visitante es una dirección IP nueva, así que los espacios de la clave se agotan tras el segundo o tercer visitante. Llama a la API desde tu propio servidor y guarda la clave allí. Los reemplazos compatibles de mapas en JavaScript cargan teselas y bibliotecas sin clave; solo sus llamadas de geocodificación deben pasar por tu servidor.

Revocación y rotación

Revoca una clave en el panel y deja de funcionar en menos de un minuto. Crea primero la nueva clave, despliégala y luego revoca la anterior; ambas funcionan mientras tanto. Las claves nunca caducan por sí solas.

Rechazos

Ninguno de estos cuenta para la cuota ni consume crédito. En los hosts compatibles se informan con la estructura del proveedor original; consulta compatibilidad.