Chuyển từ Google Maps API sang API Bản Đồ Việt Nam: Chi Phí & Code

Phần lớn các sản phẩm tại Việt Nam—ứng dụng giao hàng, form thanh toán thương mại điện tử, trang quản trị vận hành, hệ thống CRM—đều bắt đầu với Google Maps Platform vì đó là lựa chọn mặc định. Theo thời gian, thường xuất hiện hai bức tường: chi phí tăng tuyến tính theo lượng request, và dữ liệu địa chỉ không được tối ưu cho đặc thù tiếng Việt như dấu, từ viết tắt, và hệ thống phân cấp tỉnh/quận/phường.

Bài viết này so sánh thực tế về chi phí và mức độ phù hợp dữ liệu, sau đó trình bày code before/after cụ thể để chuyển ba tính năng phổ biến nhất—gợi ý địa chỉ, geocoding và reverse geocoding—sang GoGoDuk, một API bản đồ chuyên biệt cho Việt Nam dành cho lập trình viên. Mục tiêu là một quá trình chuyển đổi từng bước, ít rủi ro, thay vì viết lại toàn bộ một lần.

Vì sao các đội ngũ cân nhắc lại Google Maps cho sản phẩm Việt Nam

Google Maps là một nền tảng toàn cầu xuất sắc. Nhưng với các sản phẩm chỉ hoạt động tại Việt Nam, một API chuyên biệt có thể phù hợp hơn ở ba khía cạnh:

• Chi phí: Geocoding, Places và Autocomplete đều tính phí theo mức sử dụng. Khi lưu lượng tăng, mô hình tính theo từng request sẽ cộng dồn—và riêng autocomplete dễ gây bất ngờ cho các đội không quản lý session billing cẩn thận.
• Phù hợp dữ liệu: Địa chỉ tiếng Việt có dấu, viết tắt nhiều, các đơn vị hành chính bị đổi tên hoặc sáp nhập, và người dùng thường nhập liệu không đầy đủ. Các geocoder toàn cầu thường trả về ngữ cảnh tỉnh/quận/phường không nhất quán.
• Độ nặng tích hợp: Kéo cả một SDK bản đồ toàn cầu chỉ để phục vụ một ô địa chỉ ở form thanh toán hay một công cụ vận hành nội bộ là dư thừa so với nhu cầu thực tế.

Nếu các tính năng vị trí của bạn chỉ dành cho Việt Nam, một API ưu tiên Việt Nam sẽ thu hẹp bài toán. Để hiểu rõ hơn về định hướng này, hãy xem bài giới thiệu GoGoDuk: API Bản Đồ Việt Nam Dành Cho Lập Trình Viên.

Thực tế về chi phí của Google Maps Platform

Các API liên quan của Google Maps Platform đều tính phí theo mức sử dụng, và mô hình khác nhau theo từng tính năng. Bảng dưới đây tóm tắt cấu trúc tính phí thay vì các con số cụ thể, vì chính sách giá và tín dụng thay đổi theo thời gian—hãy luôn kiểm tra với trang giá Google Maps Platform hiện hành.

| Tính năng | Mô hình tính phí của Google | Ghi chú | | --- | --- | --- | | Geocoding | Theo mỗi 1.000 request | Địa chỉ → tọa độ; chi phí tăng tuyến tính theo lượng dùng | | Reverse Geocoding | Theo mỗi 1.000 request | Tọa độ → địa chỉ; cùng cách tính theo từng request | | Places Autocomplete | Theo session | Tính theo phiên; bỏ qua session token có thể nhân chi phí lên | | Place Details | Theo từng request | Thường đi kèm autocomplete để lấy chi tiết kết quả được chọn |

Dòng autocomplete là nơi các đội hay bất ngờ nhất. Autocomplete của Google được thiết kế để tính phí theo session—một chuỗi request theo từng phím gõ cộng với lệnh Place Details cuối cùng, gom chung dưới một session token. Nếu quên gắn session token, mỗi phím gõ có thể bị tính phí riêng lẻ, và một ô typeahead bắn request theo từng ký tự sẽ tốn kém hơn nhiều so với dự tính.

Ánh xạ tính năng Google Maps sang GoGoDuk

Trước khi đụng vào code, nên ánh xạ từng tính năng của Google sang tính năng tương ứng của GoGoDuk để biết chính xác cái gì thay cho cái gì.

| Google Maps API | Tương ứng GoGoDuk | Endpoint | | --- | --- | --- | | Places Autocomplete | Gợi ý địa chỉ | GET /v1/suggest?input=... | | Place Details | Tra cứu địa điểm | GET /v1/place/{placeId} | | Geocoding | Geocoding | GET /v1/geocode?address=... | | Reverse Geocoding | Reverse geocoding | GET /v1/reverse?lat=...&lng=... | | Geometry / ranh giới | Ranh giới hành chính | Dữ liệu tỉnh / quận / phường |

Hai khác biệt thực tế cần lưu ý. Thứ nhất là xác thực: Google truyền API key qua tham số key= trên URL, còn GoGoDuk dùng header X-API-Key—nên giữ key này phía server. Thứ hai là việc đánh giá: GoGoDuk có gói miễn phí 100 request mỗi ngày, không cần thẻ tín dụng, đủ để kiểm chứng chất lượng kết quả trên chính dữ liệu địa chỉ tiếng Việt của bạn trước khi cam kết.

Chuyển đổi gợi ý địa chỉ (autocomplete)

Autocomplete thường là tính năng có lưu lượng và chi phí cao nhất, nên hãy chuyển nó trước. Đây là luồng Google Places Autocomplete điển hình kèm session token:

// Trước — Google Places Autocomplete (tính phí theo session)
const sessionToken = new google.maps.places.AutocompleteSessionToken();
const service = new google.maps.places.AutocompleteService();

function suggestAddress(input: string) {
  return new Promise((resolve, reject) => {
    service.getPlacePredictions(
      {
        input,
        sessionToken,
        componentRestrictions: { country: "vn" },
      },
      (predictions, status) => {
        if (status !== google.maps.places.PlacesServiceStatus.OK) {
          return reject(new Error(status));
        }
        resolve(predictions ?? []);
      },
    );
  });
}

Bản tương ứng của GoGoDuk là một lệnh REST đơn thuần—không cần SDK, không cần quản lý session token, và rất dễ debounce hoặc cache:

// Sau — GoGoDuk gợi ý địa chỉ (REST thuần, phía server)
async function suggestAddress(input: string) {
  if (input.trim().length < 3) return [];

  const response = await fetch(
    `https://api.gogoduk.com/v1/suggest?input=${encodeURIComponent(input)}`,
    {
      headers: { "X-API-Key": process.env.GOGODUK_API_KEY! },
    },
  );

  if (!response.ok) {
    throw new Error("Không tải được gợi ý địa chỉ");
  }

  return response.json();
}

Mẫu tích hợp vẫn giữ nguyên: debounce đầu vào của người dùng, gọi gợi ý, để người dùng chọn một kết quả, rồi lưu định danh ổn định mà API trả về. Về phần UX—thời gian debounce, điều hướng bàn phím, và tác động đến tỷ lệ chuyển đổi—hãy xem hướng dẫn Tối ưu tỷ lệ chuyển đổi thanh toán với gợi ý địa chỉ Việt Nam.

Chuyển đổi geocoding

Geocoding biến một chuỗi địa chỉ thành tọa độ. Lệnh REST của Google trông như sau:

// Trước — Google Geocoding API
async function geocode(address: string) {
  const url = `https://maps.googleapis.com/maps/api/geocode/json?address=${encodeURIComponent(
    address,
  )}&region=vn&key=${process.env.GOOGLE_MAPS_KEY}`;

  const res = await fetch(url);
  const data = await res.json();
  const top = data.results?.[0];

  return {
    lat: top?.geometry.location.lat,
    lng: top?.geometry.location.lng,
    placeId: top?.place_id,
  };
}

Với GoGoDuk, request chuyển sang base /v1 kèm header X-API-Key, và bạn parse phản hồi về cùng một cấu trúc:

// Sau — GoGoDuk Geocoding
async function geocode(address: string) {
  const res = await fetch(
    `https://api.gogoduk.com/v1/geocode?address=${encodeURIComponent(address)}`,
    { headers: { "X-API-Key": process.env.GOGODUK_API_KEY! } },
  );

  if (!res.ok) throw new Error("Geocoding thất bại");
  const data = await res.json();
  const top = data.results?.[0];

  return {
    lat: top?.lat,
    lng: top?.lng,
    placeId: top?.placeId,
  };
}

Một thói quen tiết kiệm chi phí hữu ích: lưu lại placeId ổn định (cùng tọa độ đã giải) ngay lần geocode đầu tiên, rồi tái sử dụng thay vì geocode lại cùng một đầu vào ở mỗi request. Cách này giữ mức sử dụng ổn định cho các địa chỉ lặp lại, bất kể dùng nhà cung cấp nào.

Chuyển đổi reverse geocoding

Reverse geocoding biến tọa độ thành địa chỉ đọc được. Với Việt Nam, chi tiết quan trọng là ngữ cảnh hành chính—tỉnh, quận, phường—thứ mà geocoder toàn cầu trả về không nhất quán. Lệnh của Google:

// Trước — Google Reverse Geocoding
async function reverseGeocode(lat: number, lng: number) {
  const url = `https://maps.googleapis.com/maps/api/geocode/json?latlng=${lat},${lng}&key=${process.env.GOOGLE_MAPS_KEY}`;
  const res = await fetch(url);
  const data = await res.json();
  return data.results?.[0]?.formatted_address;
}

GoGoDuk trả về hệ phân cấp hành chính Việt Nam một cách tự nhiên, nên bạn có sẵn các trường tỉnh/quận/phường mà không phải bóc tách từ một chuỗi địa chỉ phẳng:

// Sau — GoGoDuk Reverse Geocoding
async function reverseGeocode(lat: number, lng: number) {
  const res = await fetch(
    `https://api.gogoduk.com/v1/reverse?lat=${lat}&lng=${lng}`,
    { headers: { "X-API-Key": process.env.GOGODUK_API_KEY! } },
  );

  if (!res.ok) throw new Error("Reverse geocoding thất bại");
  const data = await res.json();

  return {
    address: data.address,
    province: data.province,
    district: data.district,
    ward: data.ward,
  };
}

Các trường tỉnh/quận/phường có sẵn đặc biệt giá trị cho logistics và phân vùng giao hàng. Nếu bạn cần làm giàu địa chỉ hoặc gán vùng vận chuyển từ tọa độ, hãy xem bài Làm việc với ranh giới hành chính Việt Nam.

Checklist chuyển đổi thực tế

Bạn không cần một cú chuyển đổi "big-bang" đầy rủi ro. Hãy chuyển từng bước phía sau một adapter mỏng để có thể hoán đổi nhà cung cấp:

1. Kiểm kê mức sử dụng hiện tại. Liệt kê mọi lệnh gọi Google Maps API trong codebase và ước lượng lượng request hàng tháng theo từng tính năng.
2. Lấy key gói miễn phí. Đăng ký GoGoDuk (100 request/ngày, không cần thẻ) và thử /v1/suggest với chính dữ liệu tiếng Việt thực tế của bạn.
3. Bọc các lệnh gọi sau một adapter. Định nghĩa một interface nhỏ LocationProvider (suggest, geocode, reverse) để việc đổi nhà cung cấp chỉ là thay đổi một file.
4. Chuyển autocomplete trước. Đây thường là khoản chi phí lớn nhất, và endpoint suggest là phần dễ hoán đổi nhất.
5. Sau đó tới geocoding và reverse geocoding. Chuyển chúng sau khi autocomplete đã được kiểm chứng.
6. Cache các place ID ổn định. Tránh giải lại cùng địa chỉ ở mỗi request.
7. Chạy ở chế độ shadow. Gọi song song cả hai nhà cung cấp trong một thời gian ngắn và so sánh chất lượng kết quả trên lưu lượng thực trước khi chuyển hẳn.
8. Chuyển đổi và giám sát. Đổi adapter sang GoGoDuk rồi theo dõi độ trễ, tỷ lệ lỗi và chất lượng kết quả.

Nếu bạn không muốn viết các lệnh fetch thủ công, GoGoDuk cũng cung cấp một TypeScript SDK nhẹ tại gogoduk.com/docs/sdks/typescript.

Tổng kết và những điểm chính

Chuyển các tính năng bản đồ Việt Nam ra khỏi Google Maps gói gọn trong ba điểm:

1. Mô hình chi phí khác nhau về bản chất. Google tính theo từng request và theo session autocomplete; hãy hiểu cách tính theo session token trước khi giả định về chi phí của bạn.
2. Các tính năng cốt lõi ánh xạ rõ ràng. Autocomplete, geocoding và reverse geocoding đều có endpoint REST tương ứng trực tiếp trên GoGoDuk dùng header X-API-Key.
3. Chuyển sau một adapter, autocomplete trước. Một interface LocationProvider hoán đổi được cộng với so sánh ở chế độ shadow giúp việc chuyển đổi ít rủi ro.

Trên thực tế, việc chuyển đổi chủ yếu là hoán đổi các lệnh REST phía sau một lớp trừu tượng nhỏ—và gói miễn phí của GoGoDuk (100 request/ngày, không cần thẻ) cho phép bạn kiểm chứng chất lượng kết quả trên dữ liệu địa chỉ tiếng Việt thực tế trước khi cam kết. Về chi tiết UX autocomplete, hãy xem hướng dẫn Gợi ý địa chỉ Việt Nam cho UX thanh toán, và khám phá các endpoint cùng TypeScript SDK trong tài liệu GoGoDuk.