Autenticación

Pon la clave en el encabezado Authorization, después de la palabra Bearer y un espacio:

Authorization: Bearer gm_…

Solo buscamos la clave en ese encabezado. No existe un encabezado X-API-Key y nunca leemos una clave desde la URL, porque las URL terminan en los logs.

Para comprobar que una clave funciona, consulta tu uso. Es gratis y no cambia nada. El SDK envía el encabezado por ti en cuanto le das la clave:

curl https://api.gmaps.dev/v1/usage \
  -H "Authorization: Bearer $GMAPS_API_KEY"

Crea las claves en la consola, en Claves de API. Ponle a cada una un nombre que diga dónde se usará, como “servidor de producción” o “Claude en mi computadora”, para saber cuál revocar después.

Te mostramos la clave una sola vez, cuando la creas. No guardamos la clave en sí, así que no podemos mostrarla de nuevo: si la pierdes, crea otra. La consola muestra el inicio de cada clave y cuándo se usó por última vez, para que las distingas.

Cuántas claves puedes tener a la vez depende de tu plan. Las claves revocadas no cuentan:

Si llegaste al límite, revoca una clave que ya no uses o pasa a un plan superior.

Más claves no te dan más solicitudes. El límite por minuto se aplica a toda tu cuenta, sin importar qué clave envíe la llamada. En Límites están los números.

Una clave funciona hasta que la revocas. Revócala en la consola cuando dejes de usarla o si pudo filtrarse. Deja de funcionar al instante y no se puede deshacer. Lo que gastó sigue en la página Uso.

Para cambiar una clave sin interrupciones, crea primero la nueva, pasa tu código a ella y después revoca la anterior.

Una clave gasta tus créditos, así que trátala como una contraseña:

• No la pongas en tu código ni en git. Léela de una variable de entorno, como hacen los ejemplos de esta página.
• No la pongas en páginas web ni en apps que distribuyes, donde cualquiera puede leerla. Llama a la API desde tu servidor. Las páginas de otros sitios tampoco pueden llamarla: la API solo acepta llamadas de navegadores en gmaps.dev.
• Usa una clave distinta para cada servidor o app donde corre tu código. Así puedes revocar una sin detener las demás.

Una llamada rechazada no cambia nada y no cuesta nada. La respuesta dice qué falló:

Una clave incorrecta y una revocada reciben la misma respuesta.

Todos los errores tienen la misma forma. Esta es la respuesta a una llamada sin clave, y Errores lista todos los códigos:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Send your API key as \"Authorization: Bearer gm_…\". Create one at https://console.gmaps.dev/keys, then retry.",
    "messageKey": "serverErrors.unauthorized"
  }
}

Una app de IA puede conectarse por MCP: la app inicia sesión en gmaps.dev, te pide tu aprobación y recibe una clave de API normal, que puedes revocar en Claves de API. Los clientes configurados con una clave envían el mismo encabezado Bearer que tu código. Las llamadas se rigen por los mismos límites y gastan los mismos créditos. Listar las herramientas no necesita clave.

Cuando creas una clave, la consola muestra la configuración de MCP de tu agente con la clave ya puesta, lista para pegar.

Estas responden sin clave:

• GET /v1/attributions: los proyectos de código abierto en los que nos basamos y sus licencias.
• GET /v1/exports/{id}/download: el archivo de una exportación. El token del enlace es lo que lo abre, así que comparte el enlace solo con quien deba tener el archivo. Funciona durante 24 horas. Hay más en Exportaciones.
• GET /openapi.json: toda la API, descrita para herramientas que generan clientes.
• GET /health: si la API está activa.

Cada respuesta trae el encabezado x-request-id. Guárdalo junto con tus logs. Cuando algo salga mal, envíalo a soporte y podremos encontrar esa llamada exacta.

También puedes enviar tu propio x-request-id, de hasta 64 letras, dígitos, puntos, guiones y guiones bajos. Usamos el tuyo en lugar de inventar uno, así tus logs y los nuestros comparten un solo id. Si el tuyo no cumple esas reglas, usamos uno nuestro.

En el SDK, un error de la API trae el id en requestId.

Por cada llamada, la API registra el id, el método, la ruta, el código de estado y cuánto tardó. El servidor web que está delante de la API también registra la URL completa, con la query string, tu dirección IP y tus encabezados, excepto Authorization, y los guarda durante 180 días. Ninguno de los dos registra tu clave ni el cuerpo de la solicitud.