API tìm kiếm địa điểm (POI) cho Việt Nam: quán ăn, cửa hàng, ATM gần đây

API tìm kiếm địa điểm (POI — Points of Interest) là thứ đứng sau mọi tính năng "tìm quán ăn gần đây", "cửa hàng xung quanh", hay "ATM gần nhất" trong app của bạn. Với sản phẩm hướng tới người dùng Việt Nam, bạn cần một POI API hiểu dữ liệu địa điểm trong nước thay vì một nguồn toàn cầu phủ Việt Nam một cách hời hợt.

Bài này hướng dẫn dùng endpoint /v1/pois của GoGoDuk để tìm địa điểm gần đây theo khung nhìn bản đồ, lọc theo loại địa điểm, đánh giá và trạng thái mở cửa. Nếu bạn mới bắt đầu với việc chuyển địa chỉ thành tọa độ, đọc trước Geocoding là gì?.

POI API là gì và khi nào cần dùng

POI là các địa điểm có ý nghĩa trên bản đồ: nhà hàng, quán cà phê, cây xăng, bệnh viện, ngân hàng, siêu thị... POI API trả về danh sách các địa điểm này quanh một vị trí, kèm tọa độ để bạn vẽ pin lên bản đồ.

Dùng POI API khi sản phẩm cần:

• Tìm kiếm xung quanh: hiển thị quán ăn / cửa hàng / dịch vụ gần vị trí người dùng hoặc tài xế.
• Lớp địa điểm trên bản đồ: vẽ các nhóm POI (ăn uống, mua sắm, y tế) thành layer riêng.
• Khám phá địa phương: xây trải nghiệm tìm kiếm nhà hàng, dịch vụ, điểm tham quan.
• Vận hành & phân tích: kết hợp địa điểm với địa giới hành chính để lập kế hoạch vùng phục vụ.

Trên GoGoDuk, POI nằm cùng một nền tảng với geocoding, reverse geocoding và admin boundaries — dùng chung một API key, free 100 request/ngày, không cần thẻ tín dụng.

Gọi thử /v1/pois

Endpoint cần scope places:read và header X-API-Key. Tham số bắt buộc là bbox (khung nhìn bản đồ dạng minLng,minLat,maxLng,maxLat); thêm near để xếp hạng kết quả theo khoảng cách tới một điểm.

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

Hoặc bằng JavaScript:

async function findNearbyPlaces({ bbox, near, category }) {
  const params = new URLSearchParams({ bbox, near, category, limit: "5" });
  const res = await fetch(`https://api.gogoduk.com/v1/pois?${params}`, {
    headers: { "X-API-Key": process.env.GOGODUK_API_KEY },
  });
  return res.json();
}

Kết quả trả về là một GeoJSON FeatureCollection, các địa điểm được sắp theo khoảng cách tăng dần tới near (hoặc tâm của bbox nếu không truyền near):

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

Vì là GeoJSON chuẩn, bạn có thể đưa thẳng vào MapLibre GL JS, Leaflet hay bất kỳ thư viện bản đồ nào mà không cần chuyển đổi.

Lọc nâng cao

/v1/pois hỗ trợ vài tham số tùy chọn để thu hẹp kết quả:

• category — danh sách loại địa điểm, phân tách bằng dấu phẩy (khớp bất kỳ). Một số id thật: restaurant, cafe, bar, bakery, supermarket, convenience_store, hospital, pharmacy, bank, atm, gas_station, lodging, shopping_mall. Lấy danh sách đầy đủ kèm nhãn tiếng Việt qua GET /v1/categories.
• min_rating — chỉ lấy địa điểm có đánh giá ≥ giá trị này (trong khoảng 0–5).
• open_now — đặt true để chỉ lấy địa điểm đang mở cửa.
• near — lng,lat làm tâm xếp hạng theo khoảng cách.
• limit — số kết quả trả về, từ 1 đến 10 (mặc định 5).

Ví dụ: tìm tối đa 10 quán cà phê đang mở cửa, đánh giá từ 4 sao trở lên, gần một vị trí:

curl "https://api.gogoduk.com/v1/pois?bbox=106.69,10.76,106.71,10.78&near=106.70,10.77&category=cafe&min_rating=4&open_now=true&limit=10" \
  -H "X-API-Key: $GOGODUK_API_KEY"

Các con số (số quán, đánh giá) ở trên chỉ là ví dụ minh hoạ cho cú pháp. Kết quả thực tế phụ thuộc dữ liệu quanh khu vực bạn truy vấn.

Lớp POI trên bản đồ với vector tiles

Khi muốn hiển thị nhiều địa điểm trên một bản đồ tương tác (không phải danh sách ngắn), dùng endpoint vector tile thay vì gọi /v1/pois liên tục:

GET /v1/pois/tiles/{z}/{x}/{y}

Map renderer sẽ tự tải các tile theo khung nhìn và mức zoom, nên bạn vẽ được category map (lớp ăn uống, mua sắm, y tế...) mà vẫn nhẹ. Khi người dùng bấm vào một pin, lấy chi tiết của địa điểm đó bằng:

GET /v1/pois/{placeId}

Một nền tảng, một API key

Điểm mạnh của việc dùng POI trên GoGoDuk là nó nằm chung hệ với các API location khác cho Việt Nam: bạn dùng geocoding & autocomplete địa chỉ để người dùng nhập điểm xuất phát, /v1/pois để tìm địa điểm xung quanh, và admin boundaries để giới hạn theo vùng phục vụ — tất cả sau một API key duy nhất.

Vài hướng áp dụng thực tế:

• App giao hàng / store-finder: tìm cửa hàng gần khách rồi vẽ lên bản đồ. Xem thêm cách dựng Store Locator cho Việt Nam.
• Vận hành theo vùng: kết hợp POI với phân vùng giao hàng.

Tham khảo đầy đủ tham số và response trong tài liệu API và trang Vietnam POI API.

Bắt đầu

/v1/pois nằm trong gói free của GoGoDuk: 100 request/ngày mỗi tài khoản, đủ cho prototype và nhiều app nhỏ chạy thật. Tạo tài khoản, lấy API key, và thử query đầu tiên ngay trong vài phút.