TypeScript SDK

The package is gmaps-sdk. It has no dependencies of its own.

npm i gmaps-sdk

Give it your key, here read from an environment variable. Each method then makes one call and returns what the API answers under data:

import { createClient } from "gmaps-sdk";

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

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

What createClient takes:

To give one call a different time limit, or to cancel it, pass { timeoutMs, signal } as its last argument.

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

If a call gets no answer, or an error on our side (a 5xx), the SDK sends it again about 1 second later, and again about 2 seconds after that. It does this only for calls that are safe to run twice: reads, quotes, coverage checks, cancels, and webhook changes and deletes. A search, a new collection, a new export, a new webhook and a webhook test are never sent again this way, because the first try may already have run, and a second could cost credits, send something twice, or make a second export in your list. After a 408, 425 or 429 that asks for a wait of 10 seconds or less, any call waits and goes again.

Each method takes one object with the same fields as its API call. Methods with no fields, like usage.get(), take only the options.

When a search can't fill limit with places we have saved, its answer includes a collection that is finding the rest. watchCollection hands you each new place as it arrives:

const result = await gmaps.places.search({
  keywords: ["bakery"],
  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);
  }
}

• Each event has a type and its data. place brings a new place, progress brings the counts so far, and done comes last. Live progress lists every type. A large collection stops sending place events after a set number, so read its places with collections.places once it ends.
• The loop ends by itself after done. To stop sooner, break out of it.
• If the connection drops, it connects again and carries on after the last event it gave you, so you never get an event twice or miss one. After too many drops in a row, with no event between them, it throws a GmapsError with NETWORK_ERROR.

What its second argument takes:

You don't have to watch. You can run the same search again later, when the new places come back for free, or ask the search to wait for them. Search explains both.

Every failed call throws a GmapsError. It carries what the API said, so your code can tell one problem from another:

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}`);
}

Four codes come from the SDK itself, when there is no answer it can use:

• TIMEOUT: the API didn't answer within timeout.
• NETWORK_ERROR: the API couldn't be reached, or the answer broke off.
• INVALID_RESPONSE: the status said success, but the body was not an answer from the API: it had no data, had an error, or was not JSON. Most often, baseUrl is missing /v1.
• HTTP_ERROR: an error came back that isn't in our format, most often from something between you and the API.

If you cancel a call with your own signal, the SDK throws the signal's reason instead. Options that can't work, like a baseUrl that isn't http or https, throw as soon as you create the client.

verifyWebhook tells you whether a request really came from us. Give it your endpoint's secret, the raw body and the x-gmaps-signature header:

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);

It returns false for every kind of failure: no header, a different secret, a changed body, or a signature more than 5 minutes old. Read the body as text and parse it only after the check: parsing it and writing it back changes its bytes. Webhooks covers the rest.

Every answer is typed, and each answer type is exported by name for your own code:

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

Each method's parameters are exported too, such as SearchPlacesParams, so you can type a call before you make it:

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

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

• Node 22 or newer, Bun, or any runtime with fetch, AbortSignal.any and AbortSignal.timeout.
• It's an ES module and ships its own type declarations. Load it with import.
• It has no dependencies. Calls use the runtime's own fetch, and verifyWebhook uses Web Crypto.
• It runs in a browser too, but keep your key on a server. In a browser, anyone can read it.