SDK de TypeScript

El paquete es gmaps-sdk. No tiene dependencias propias.

npm i gmaps-sdk

Pásale tu clave, que aquí se lee de una variable de entorno. Cada método hace una llamada y devuelve lo que responde la API en data:

import { createClient } from "gmaps-sdk";

const gmaps = createClient({ apiKey: process.env.GMAPS_API_KEY });

const result = await gmaps.places.search({
  keywords: ["panadería"],
  geo: { location: "Curitiba, PR" }
});
console.log(result.places.map((place) => place.identity.name));

Qué acepta createClient:

Para darle a una llamada otro límite de tiempo, o para cancelarla, pasa { timeoutMs, signal } como último argumento.

const usage = await gmaps.usage.get({ timeoutMs: 5000 });

Si una llamada no recibe respuesta, o recibe un error de nuestro lado (un 5xx), el SDK la envía de nuevo cerca de 1 segundo después, y otra vez cerca de 2 segundos más tarde. Solo lo hace con llamadas que se pueden ejecutar dos veces sin riesgo: lecturas, estimaciones, consultas de cobertura, cancelaciones, y cambios y eliminaciones de webhooks. Una búsqueda, una recopilación nueva, una exportación nueva, un webhook nuevo y una prueba de webhook nunca se reenvían así, porque el primer intento pudo haberse ejecutado ya, y un segundo podría gastar créditos, enviar algo dos veces o crear una segunda exportación en tu lista. Después de un 408, 425 o 429 que pida una espera de 10 segundos o menos, cualquier llamada espera y se envía de nuevo.

Cada método recibe un objeto con los mismos campos que su llamada de la API. Los que no tienen campos, como usage.get(), reciben solo las opciones.

Cuando los lugares que tenemos guardados no alcanzan para limit, la respuesta de la búsqueda incluye una collection que busca el resto. watchCollection te entrega cada lugar nuevo en cuanto llega:

const result = await gmaps.places.search({
  keywords: ["panadería"],
  geo: { location: "Curitiba, PR" }
});

if (result.collection) {
  for await (const frame of gmaps.watchCollection(result.collection.id)) {
    if (frame.type === "place") console.log(frame.data);
  }
}

• Cada evento tiene un type y sus datos en data. place trae un lugar nuevo, progress trae los conteos hasta ese momento y done llega al final. Progreso en vivo lista todos los tipos. Una recopilación grande deja de enviar eventos place después de cierto número, así que lee sus lugares con collections.places cuando termine.
• El bucle termina solo después de done. Para detenerlo antes, sal de él con break.
• Si la conexión se cae, se conecta de nuevo y sigue después del último evento que te entregó, así que nunca recibes un evento dos veces ni te pierdes uno. Si se cae demasiadas veces seguidas, sin ningún evento entre una y otra, lanza un GmapsError con NETWORK_ERROR.

Qué acepta su segundo argumento:

No tienes que seguirla en vivo. Puedes repetir la misma búsqueda más tarde, cuando los lugares nuevos llegan gratis, o pedirle a la búsqueda que los espere con wait. Búsqueda explica las dos formas.

Toda llamada que falla lanza un GmapsError. Trae lo que dijo la API, para que tu código distinga un problema de otro:

import { GmapsError } from "gmaps-sdk";

try {
  await gmaps.usage.get();
} catch (error) {
  if (!(error instanceof GmapsError)) throw error;
  console.error(error.status, error.code, error.message);
  console.error(`Request id: ${error.requestId}`);
}

Cuatro códigos vienen del propio SDK, cuando no hay una respuesta que pueda usar:

• TIMEOUT: la API no respondió dentro de timeout.
• NETWORK_ERROR: no se pudo llegar a la API, o la respuesta se cortó a la mitad.
• INVALID_RESPONSE: el estado indicaba éxito, pero el cuerpo no era una respuesta de la API: no tenía data, traía un error o no era JSON. Casi siempre falta /v1 en baseUrl.
• HTTP_ERROR: llegó un error que no tiene nuestro formato, casi siempre de algo que está entre tú y la API.

Si cancelas una llamada con tu propio signal, el SDK lanza el reason de ese signal en lugar del error. Las opciones que no pueden funcionar, como un baseUrl que no es http ni https, lanzan un error en cuanto creas el cliente.

verifyWebhook te dice si una solicitud realmente vino de nosotros. Pásale el secreto de firma de tu endpoint, el cuerpo sin procesar y el encabezado x-gmaps-signature:

import { verifyWebhook } from "gmaps-sdk";

const body = await request.text();
const signed = await verifyWebhook(
  process.env.GMAPS_WEBHOOK_SECRET,
  body,
  request.headers.get("x-gmaps-signature"),
);
if (!signed) return new Response(null, { status: 400 });
const event = JSON.parse(body);

Devuelve false ante cualquier falla: sin encabezado, otro secreto, un cuerpo modificado o una firma de más de 5 minutos. Lee el cuerpo como texto y analiza el JSON solo después de verificar: si lo analizas y lo vuelves a escribir, sus bytes cambian. Webhooks explica el resto.

Toda respuesta está tipada, y cada tipo de respuesta se exporta por su nombre para que lo uses en tu código:

import type { CollectionDto, PlaceDto, SearchResultDto } from "gmaps-sdk";

Los parámetros de cada método también se exportan, como SearchPlacesParams, para que puedas tipar una llamada antes de hacerla:

import type { SearchPlacesParams } from "gmaps-sdk";

const ask: SearchPlacesParams = {
  keywords: ["panadería"],
  geo: { location: "Curitiba, PR" }
};

• Node 22 o más reciente, Bun, o cualquier entorno con fetch, AbortSignal.any y AbortSignal.timeout.
• Es un módulo ES y trae sus propias declaraciones de tipos. Cárgalo con import.
• No tiene dependencias. Las llamadas usan el fetch del propio entorno, y verifyWebhook usa Web Crypto.
• También funciona en un navegador, pero deja tu clave en un servidor. En un navegador, cualquiera puede leerla.