GET /v1/pois

Tìm địa điểm (POI) ở Việt Nam trong một bounding box, xếp theo khoảng cách.

Trả về một GeoJSON FeatureCollection gồm các địa điểm (nhà hàng, quán cà phê, ATM, bệnh viện...) bên trong một bounding box, sắp xếp theo khoảng cách tới near (hoặc tới tâm của box). Dùng cho tìm kiếm xung quanh, lớp địa điểm trên bản đồ, và khám phá địa phương ở Việt Nam.

Scope yêu cầu: places:read

Trang này cũng mô tả hai endpoint đi kèm: /v1/pois/tiles/{z}/{x}/{y} (vector tiles cho lớp bản đồ) và /v1/pois/{placeId} (chi tiết đầy đủ của một địa điểm).

Request

GET /v1/pois?bbox=106.69,10.76,106.71,10.78&near=106.70,10.77&category=restaurant,cafe&limit=5
X-API-Key: gdk_live_xxxxxxxxxxxxxxxxxxxxxxxx

curl -G "https://api.gogoduk.com/v1/pois" \
-H "X-API-Key: $GOGODUK_API_KEY" \
--data-urlencode "bbox=106.69,10.76,106.71,10.78" \
--data-urlencode "near=106.70,10.77" \
--data-urlencode "category=restaurant,cafe" \
--data-urlencode "limit=5"

Tham số query

Tên	Bắt buộc	Mô tả
`bbox`	có	Bounding box dạng `minLng,minLat,maxLng,maxLat` (vd `106.69,10.76,106.71,10.78`).
`near`	không	`lng,lat` làm tâm xếp hạng theo khoảng cách. Mặc định là tâm của `bbox`.
`limit`	không	Số POI trả về, `1`–`10`. Mặc định `5`.
`category`	không	Danh sách id category, phân tách bằng dấu phẩy (khớp bất kỳ). Xem Categories.
`min_rating`	không	Chỉ lấy POI có đánh giá ≥ giá trị này (`0`–`5`).
`open_now`	không	`true` để chỉ lấy POI đang mở cửa tại thời điểm gọi.

Response

Một GeoJSON FeatureCollection. Feature trong danh sách chỉ mang các thuộc tính nhẹ để response gọn — place_id, name, primary_type. Lấy phần còn lại qua endpoint chi tiết.

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": { "type": "Point", "coordinates": [106.701, 10.772] },
      "properties": {
        "place_id": "poi_abc123",
        "name": "Quán ăn ví dụ",
        "primary_type": "restaurant"
      }
    }
  ]
}

Trường response

Trường	Kiểu	Mô tả
`type`	string	Luôn là `FeatureCollection`.
`features[]`	array	POI xếp theo khoảng cách (gần nhất trước).
`features[].geometry.coordinates`	array	`[lng, lat]` của POI.
`features[].properties.place_id`	string	Mã định danh POI.
`features[].properties.name`	string	Tên hiển thị.
`features[].properties.primary_type`	string	Id category chính (vd `restaurant`).

POI vector tiles

Với các lớp bản đồ hiển thị nhiều POI cùng lúc, dùng Mapbox Vector Tiles thay vì gọi /v1/pois liên tục:

GET /v1/pois/tiles/{z}/{x}/{y}
X-API-Key: gdk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Map renderer tải tile theo mức zoom (z) và toạ độ tile (x/y). Mỗi response tile cũng cấp một X-POI-Token ngắn hạn cho từng feature, mà endpoint chi tiết yêu cầu.

Scope yêu cầu: places:read

Chi tiết POI

Lấy thông tin đầy đủ của một POI theo place_id:

GET /v1/pois/{placeId}
X-API-Key: gdk_live_xxxxxxxxxxxxxxxxxxxxxxxx
X-POI-Token: <token từ response tile>

Header X-POI-Token là bắt buộc — đây là token theo từng feature trả về trong response vector tile. Kết quả là một object duy nhất với đầy đủ thuộc tính:

{
  "result": {
    "place_id": "poi_abc123",
    "name": "Quán ăn ví dụ",
    "primary_type": "restaurant",
    "formatted_address": "12 Nguyễn Huệ, Bến Nghé, Quận 1",
    "city": "Hồ Chí Minh",
    "district": "Quận 1",
    "rating": 4.5,
    "user_rating_count": 120,
    "opening_hours": { "...": "..." },
    "phone": "028 1234 5678",
    "website": "https://example.com",
    "price_level": "PRICE_LEVEL_MODERATE"
  }
}

Các trường tùy chọn (rating, user_rating_count, opening_hours, phone, international_phone, website, price_level) chỉ xuất hiện khi có dữ liệu, nên hãy kiểm tra key trước khi đọc.

Scope yêu cầu: places:read

Lỗi thường gặp

400 INVALID_BBOX — bbox không đúng dạng minLng,minLat,maxLng,maxLat.
400 — giá trị min của bbox không nhỏ hơn giá trị max.
401 INVALID_API_KEY — không nhận diện được key.
403 INSUFFICIENT_SCOPE — key thiếu scope places:read.
404 — /v1/pois/{placeId} — không có POI cho place_id đó.
429 RATE_LIMIT_MINUTE — chờ rồi thử lại theo trường retry_after.

GET /v1/pois

On this page