Tài liệu tham khảo API

Tất cả endpoint của GoGoDuk trong nháy mắt — method, scope, cấu trúc request, cấu trúc response.

API GoGoDuk dùng REST + JSON. Xác thực bằng header X-API-Key trên mọi request được bảo vệ. Mỗi endpoint yêu cầu một scope cụ thể; hãy tạo các key chỉ cấp đúng những gì client của bạn thực sự cần.

Base URL

https://api.gogoduk.com

Đối với phát triển cục bộ, cùng các đường dẫn này được phục vụ tại http://localhost:8081.

Các endpoint

Geocoding

Tất cả các endpoint này đều yêu cầu scope geocoding:read.

Method	Path	Mục đích
GET	`/v1/suggest`	Gợi ý autocomplete cho một query chưa hoàn chỉnh.
GET	`/v1/place/resolve`	Bản ghi đầy đủ (lat / lon / địa chỉ) cho một `placeId`.
GET	`/v1/reverse`	Reverse geocode theo độ gần cho một tọa độ.
GET	`/v1/reverse-geocode`	Tra cứu ranh giới hành chính (tỉnh + quận).

Địa điểm & POI

Yêu cầu scope places:read.

Method	Path	Mục đích
GET	`/v1/pois`	Liệt kê các địa điểm quan tâm theo query / box.
GET	`/v1/pois/tiles/{z}/{x}/{y}`	Vector tile của các POI cho tile XYZ đã cho.
GET	`/v1/pois/{placeId}`	Chi tiết một POI. Trả lại tile token.

Ranh giới hành chính

Yêu cầu scope admin_boundaries:read.

Method	Path	Mục đích
GET	`/v1/admin-boundaries`	Polygon cấp tỉnh / quận (GeoJSON hoặc WKT).

Demo công khai

Method	Path	Mục đích
GET	`/v1/demo/suggest`	Cùng cấu trúc với `/v1/suggest`. Không cần API key. Rate-limit theo IP ở mức 30 req/phút.

Health

Method	Path	Mục đích
GET	`/health`	Trả về `{status: "ok"}` và chỉ health của Postgres. Không cần API key.

Request envelope

Mọi lần gọi được bảo vệ:

GET /v1/<endpoint>?<params>
Host: api.gogoduk.com
X-API-Key: gdk_live_xxxxxxxxxxxxxxxxxxxxxxxx
X-Request-ID: <optional client-generated UUID; echoed back>

Response header (mọi response được bảo vệ)

X-Request-ID: 8f0e1c54-...
X-RateLimit-Limit-Minute: 60
X-RateLimit-Remaining-Minute: 59
X-RateLimit-Limit-Day: 1000
X-RateLimit-Remaining-Day: 999

Xem Rate limit để biết bảng hạn mức đầy đủ.

Error envelope

Tất cả các lỗi đều theo cùng một cấu trúc:

{
  "error": "human readable message",
  "code": "SNAKE_CASE_CODE",
  "request_id": "8f0e1c54-...",
  "retry_after": 27
}

retry_after chỉ xuất hiện trên các response 429. Xem Lỗi để biết mọi code.

Quickstart

Nếu bạn chưa từng gọi API, hãy nhảy tới Quickstart — một bộ ba curl + JS + Python hoạt động được, hoàn thành trong chưa đầy một phút.

Tài liệu tham khảo API

On this page