Reverse Geocoding API: xác định tỉnh/huyện từ tọa độ GPS ở Việt Nam

Nếu bạn đã có tọa độ GPS, bạn không cần parse chuỗi địa chỉ lộn xộn để biết điểm đó thuộc tỉnh/huyện nào ở Việt Nam. Reverse Geocoding API có thể chuyển lat,lng thành ngữ cảnh hành chính hiện hành.

Điều này quan trọng với vùng giao hàng, vị trí tài xế, vùng phủ chi nhánh, territory CRM và báo cáo theo tỉnh/huyện. Tọa độ ổn định hơn tên địa chỉ, đặc biệt khi đơn vị hành chính thay đổi.

Bài này cố ý tách khỏi bài giới thiệu dataset ranh giới hành chính. Nếu cần hiểu dataset, đọc Ranh giới hành chính Việt Nam. Nếu cần chuẩn hóa địa chỉ cũ sau sáp nhập 2025, đọc hướng dẫn chuẩn hóa địa chỉ sau sáp nhập.

Vấn đề

Nhiều hệ thống lưu địa chỉ dạng text rồi cố suy ra tỉnh, huyện hoặc vùng dịch vụ từ chuỗi đó. Cách này dễ hỏng khi:

• User gõ tên huyện/phường cũ.
• Địa chỉ thiếu dấu hoặc viết tắt.
• Tỉnh/huyện đổi sau cập nhật hành chính.
• App cần phân loại hàng nghìn điểm lịch sử một cách nhất quán.

Nếu đã có tọa độ, nguồn sự thật tốt hơn là geometry. Tra cứu point-in-polygon trả lời câu hỏi: "Điểm này nằm trong ranh giới hành chính nào?"

Khi nào cần dùng

Reverse geocoding theo tọa độ hữu ích khi vị trí đến từ GPS, map pin hoặc địa chỉ đã geocode trước đó.

Các use case phổ biến:

• Delivery zone: quyết định đơn thuộc chi nhánh, kho hoặc khu phụ phí nào.
• Theo dõi tài xế: gắn GPS realtime với tỉnh/huyện để điều phối.
• Vùng phủ cửa hàng: kiểm tra khách có nằm trong khu vực phục vụ không.
• CRM territory: gom khách theo tỉnh/huyện hiện hành.
• Báo cáo vận hành: giữ dashboard ổn định sau đổi tên hành chính.

Lợi thế chính là độ bền. Chuỗi địa chỉ có thể đổi, nhưng tọa độ vẫn là cùng một điểm ngoài đời.

Pattern triển khai

Gọi reverse geocoding sau khi thu được tọa độ. Tọa độ có thể đến từ browser geolocation, app mobile, map pin hoặc kết quả autocomplete địa chỉ.

curl -H "X-API-Key: gdk_live_..." \
  "https://api.gogoduk.com/v1/reverse-geocode?lat=21.03&lng=105.85"

Ví dụ response:

{
  "lat": 21.03,
  "lng": 105.85,
  "city": "Hà Nội",
  "district": "Đống Đa"
}

Trong backend service, nên persist cả tọa độ lẫn kết quả hành chính:

async function classifyPoint({ lat, lng }) {
  const res = await fetch(
    `https://api.gogoduk.com/v1/reverse-geocode?lat=${lat}&lng=${lng}`,
    { headers: { "X-API-Key": process.env.GOGODUK_API_KEY } },
  );
 
  if (!res.ok) throw new Error("reverse geocoding failed");
  return res.json();
}

Lưu cả hai giá trị. Tọa độ cho phép bạn phân loại lại sau này nếu ranh giới hoặc rule kinh doanh thay đổi.

Data model nên dùng

Với hệ thống vận hành, đừng chỉ lưu formatted address.

Một record vị trí thực dụng nên giống như:

{
  "addressText": "226 Vạn Phúc, Ba Đình, Hà Nội",
  "lat": 21.0345,
  "lng": 105.8125,
  "province": "Hà Nội",
  "district": "Ba Đình",
  "source": "user_selected_suggestion",
  "classifiedAt": "2026-05-29T00:00:00.000Z"
}

classifiedAt hữu ích khi sau này bạn cần audit kết quả được tạo từ phiên bản ranh giới nào.

Lỗi thường gặp

Lỗi đầu tiên là tin text hơn tọa độ. Nếu địa chỉ ghi một huyện nhưng tọa độ nằm trong huyện khác, logic giao hàng và báo cáo thường nên tin tọa độ, đồng thời flag record để kiểm tra.

Lỗi thứ hai là chỉ reverse geocode lúc hiển thị. Nếu tỉnh/huyện ảnh hưởng giá, routing hoặc analytics, hãy phân loại và lưu kết quả ở server.

Lỗi thứ ba là bỏ qua điểm lỗi hoặc ngoài Việt Nam. App cần xử lý null result, điểm rơi ra biển, GPS accuracy thấp và tọa độ ngoài Việt Nam.

GoGoDuk phù hợp ở đâu

Endpoint /docs/endpoints/reverse-geocode của GoGoDuk dựa trên dữ liệu ranh giới hành chính Việt Nam và được thiết kế để xác định tỉnh/huyện từ tọa độ.

Dùng endpoint này cùng với:

• Autocomplete địa chỉ cho input từ user.
• GPS lưu từ app mobile.
• Polygon ranh giới hành chính khi cần vẽ vùng dịch vụ trên bản đồ.

Nếu muốn hiểu sâu dataset ranh giới, đọc Ranh giới hành chính Việt Nam. Nếu bài toán chính là địa chỉ text cũ sau sáp nhập 2025, đọc hướng dẫn chuẩn hóa địa chỉ.

Câu hỏi thường gặp

Reverse geocoding khác geocoding thế nào? Geocoding chuyển địa chỉ thành tọa độ. Reverse geocoding chuyển tọa độ thành địa chỉ hoặc khu vực hành chính.

Vì sao nên dùng tọa độ thay vì parse địa chỉ? Tọa độ bền hơn. Tên địa chỉ có thể sai dấu, viết tắt hoặc đổi sau cập nhật hành chính, nhưng điểm vẫn nằm trong một ranh giới cụ thể.

Có phân loại dữ liệu khách hàng lịch sử được không? Có, nếu record có tọa độ. Chạy lại reverse geocoding để gắn tỉnh/huyện hiện hành.

Nếu điểm nằm gần ranh giới thì sao? Hãy lưu cả tọa độ và thời điểm phân loại. Với nghiệp vụ rủi ro cao, thêm manual review cho GPS accuracy thấp hoặc điểm gần mép vùng dịch vụ.

Thử ngay

Gửi một điểm thật từ app của bạn:

curl -H "X-API-Key: gdk_live_..." \
  "https://api.gogoduk.com/v1/reverse-geocode?lat=10.7769&lng=106.7009"

Tạo API key miễn phí, rồi test các điểm trong dữ liệu giao hàng, tài xế hoặc khách hàng của bạn.