TypeScript SDK

SDK chính thức @gogoduk/sdk cho TypeScript và JavaScript — cài đặt, cấu hình và gọi mọi endpoint từ Node, trình duyệt, Bun, Deno hoặc các edge runtime.

@gogoduk/sdk là client TypeScript chính thức cho GoGoDuk Map API. Năm method có kiểu rõ ràng, một error class nhất quán, build cả ESM + CJS, không phụ thuộc runtime nào.

npm: @gogoduk/sdk
Mã nguồn: github.com/gogoduk-io/sdk-ts
Giấy phép: MIT

Install

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

Yêu cầu Node 18+ để có fetch toàn cục. Hoạt động trên trình duyệt, Bun, Deno và các edge runtime của Vercel/Cloudflare mà không cần 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);

Lấy API key của bạn tại 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()`

Gợi ý autocomplete. Input phải có ít nhất 2 ký tự.

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

Truyền cùng một sessionToken qua các lần gọi trong cùng một session autocomplete, sau đó chuyển tiếp nó cho placeResolve để đóng session tính phí. Xem tài liệu tham khảo endpoint suggest.

`reverse()`

Reverse geocode dựa trên độ gần — (các) địa chỉ đã biết gần nhất với một điểm.

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

Xem tài liệu tham khảo endpoint reverse.

`placeResolve()`

Phân giải một placeId từ suggest thành thông tin chi tiết đầy đủ của địa điểm.

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

Xem tài liệu tham khảo endpoint place/resolve.

`reverseGeocode()`

Tra cứu theo ranh giới hành chính — trả về tỉnh và quận chứa điểm đó thông qua ST_Contains của PostGIS.

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

city và district có thể là null nếu không có ranh giới nào chứa điểm đó. Xem tài liệu tham khảo endpoint reverse-geocode.

`adminBoundaries()`

Polygon của tỉnh và quận ở định dạng GeoJSON hoặc 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

Mọi method đều reject với GoGoDukError khi gặp response không phải 2xx hoặc khi lỗi truyền tải:

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	Ý nghĩa
`status`	HTTP status. `0` cho lỗi mạng hoặc timeout.
`message`	Field `message` / `error` từ server, dự phòng về `HTTP <status>`.
`requestId`	Header `x-request-id` từ response — hãy đính kèm khi báo lỗi.
`body`	JSON đã parse hoặc văn bản thô từ phần body của response.

Versioning

Các bản phát hành trước 1.0 (0.x.y) có thể chứa thay đổi phá vỡ (breaking change) ở các lần nâng minor (0.1 → 0.2). Changelog đầy đủ nằm tại CHANGELOG.md.

Hình dạng của SDK bám theo API. adminBoundaries hiện trả thêm các field tùy chọn như province_name, population, area_km2, pre_merge_info, admin_center và centroid.

Roadmap

Python SDK (@gogoduk/sdk-python) khi có nhu cầu. Hãy cho chúng tôi biết tại [email protected] nếu điều này giúp bạn tháo gỡ rào cản.
Wrapper cho POI search (/v1/pois và POI tiles) — tạm hoãn cho đến khi pipeline binary MVT ổn định.

TypeScript SDK

On this page