TypeScript SDK

Official @gogoduk/sdk for TypeScript and JavaScript — install, configure, and call every endpoint from Node, the browser, Bun, Deno, or edge runtimes.

@gogoduk/sdk is the official TypeScript client for the GoGoDuk Map API. Five typed methods, one consistent error class, ESM + CJS builds, no runtime dependencies.

npm: @gogoduk/sdk
Source: github.com/gogoduk-io/sdk-ts
License: MIT

Install

npm install @gogoduk/sdk
# or
pnpm add @gogoduk/sdk
# or
yarn add @gogoduk/sdk

Requires Node 18+ for the global fetch. Works in browsers, Bun, Deno, and Vercel/Cloudflare edge runtimes without a polyfill.

Quick start

import { GoGoDukClient } from "@gogoduk/sdk";
 
const client = new GoGoDukClient({ apiKey: process.env.GOGODUK_API_KEY! });
 
const { predictions } = await client.suggest({ input: "Hà Nội" });
const { result } = await client.placeResolve({ id: predictions[0].placeId });
console.log(result.address, result.lat, result.lon);

Get your API key from the dashboard.

Configuration

new GoGoDukClient({
  apiKey: "gdk_live_...",       // required
  baseUrl: "https://api.gogoduk.com", // default
  timeoutMs: 10_000,            // default; 0 disables
  fetch: customFetch,           // inject for tests / polyfill
  defaultHeaders: { "X-Tenant": "..." }, // merged into every request
});

Methods

`suggest()`

Autocomplete predictions. Input must be at least 2 characters.

const { predictions } = await client.suggest({
  input: "Hào Nam",
  lang: "vi",
  country: "VN",
  sessionToken: "uuid",
  focusLat: 21.03,
  focusLon: 105.85,
});

Pass the same sessionToken across calls in one autocomplete session, then forward it to placeResolve to close the billing session. See the suggest endpoint reference.

`reverse()`

Proximity-based reverse geocode — nearest known address(es) to a point.

const { results } = await client.reverse({
  lat: 21.03,
  lon: 105.85,
  size: 1,        // max 5
  radiusKm: 0.05, // capped server-side at 0.1
});

See reverse endpoint reference.

`placeResolve()`

Resolve a placeId from suggest into full place details.

const { result } = await client.placeResolve({
  id: "place_abc",
  sessionToken: "uuid",
});

See place/resolve endpoint reference.

`reverseGeocode()`

Admin-boundary lookup — returns the province and district that contain the point via PostGIS ST_Contains.

const { city, district } = await client.reverseGeocode({
  lat: 21.03,
  lng: 105.85,
  levels: [4, 8],
});

city and district can be null if no boundary contains the point. See reverse-geocode endpoint reference.

`adminBoundaries()`

Province and district polygons as GeoJSON or WKT.

const boundaries = await client.adminBoundaries({
  levels: [4, 8],
  format: "geojson",
  countryCode: "VN",
  tolerance: 0.001,
});
 
for (const province of boundaries.admin_level_4 ?? []) {
  console.log(province.name, province.boundary);
}

Error handling

Every method rejects with GoGoDukError on non-2xx responses or transport failures:

import { GoGoDukError } from "@gogoduk/sdk";
 
try {
  await client.suggest({ input: "ab" });
} catch (err) {
  if (err instanceof GoGoDukError) {
    console.error(err.status, err.message, err.requestId, err.body);
  }
}

Property	Meaning
`status`	HTTP status. `0` for network or timeout failures.
`message`	Server `message` / `error` field, falling back to `HTTP <status>`.
`requestId`	`x-request-id` header from the response — include when reporting bugs.
`body`	Parsed JSON or raw text from the response body.

Versioning

Pre-1.0 releases (0.x.y) may include breaking changes at minor bumps (0.1 → 0.2). The full changelog lives at CHANGELOG.md.

The SDK shape tracks the API. adminBoundaries currently exposes optional metadata including province_name, population, area_km2, pre_merge_info, admin_center, and centroid.

Roadmap

Python SDK (@gogoduk/sdk-python) once there's demand. Tell us at [email protected] if this would unblock you.
POI search wrapper (/v1/pois and POI tiles) — deferred until the binary MVT pipeline stabilizes.

TypeScript SDK

On this page