API Reference

All GoGoDuk endpoints at a glance — methods, scopes, request shape, response shape.

The GoGoDuk API is REST + JSON. Authenticate with the X-API-Key header on every protected request. Each endpoint requires one specific scope; mint keys that grant only what your client actually needs.

Base URL

https://api.gogoduk.com

For local development the same paths are served at http://localhost:8081.

Endpoints

Geocoding

These endpoints all require the geocoding:read scope.

Method	Path	Purpose
GET	`/v1/suggest`	Autocomplete predictions for a partial query.
GET	`/v1/place/resolve`	Full record (lat / lon / address) for a `placeId`.
GET	`/v1/reverse`	Proximity reverse geocode for a coordinate.
GET	`/v1/reverse-geocode`	Admin-boundary lookup (province + district).

Places & POIs

Require the places:read scope.

Method	Path	Purpose
GET	`/v1/pois`	List places of interest by query / box.
GET	`/v1/pois/tiles/{z}/{x}/{y}`	Vector tile of POIs for the given XYZ tile.
GET	`/v1/pois/{placeId}`	Single POI detail. Echoes the tile token.

Admin Boundaries

Requires the admin_boundaries:read scope.

Method	Path	Purpose
GET	`/v1/admin-boundaries`	Provincial / district polygons (GeoJSON or WKT).

Public demo

Method	Path	Purpose
GET	`/v1/demo/suggest`	Same shape as `/v1/suggest`. No API key required. IP-rate-limited at 30 req/min.

Health

Method	Path	Purpose
GET	`/health`	Returns `{status: "ok"}` and Postgres-only health. No API key.

Request envelope

Every protected call:

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

Response headers (every protected response)

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

See Rate limits for the full quota table.

Error envelope

All errors follow the same shape:

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

retry_after is only present on 429 responses. See Errors for every code.

Quickstart

If you've never called the API, jump to the Quickstart — a working curl + JS + Python triple that finishes in under a minute.

API Reference

On this page