Google Maps API bị chặn ở Việt Nam: lỗi thường gặp và hướng xử lý

Nếu sản phẩm của bạn ở Việt Nam và Google Maps API đột nhiên không chạy, lỗi không nhất thiết nằm ở code frontend. Rất nhiều trường hợp hỏng từ billing, region, quota hoặc cấu hình API key trước khi request chạm tới logic ứng dụng.

Bài này dành cho developer đã có tích hợp Google Maps và cần hướng xử lý thực dụng: xác định lỗi nằm ở đâu, phân biệt vấn đề billing với vấn đề code, rồi quyết định nên tiếp tục debug Google hay chuyển phần geocoding Việt Nam sang API chuyên biệt.

Đây không phải bài so sánh toàn bộ nhà cung cấp bản đồ. Nếu cần bức tranh rộng hơn, đọc Top Map API Việt Nam 2026. Bài này chỉ tập trung vào trường hợp Google Maps API bị lỗi hoặc khó dùng ở Việt Nam.

Vấn đề thường gặp

Google Maps Platform cần đủ nhiều điều kiện: project đúng, API đã bật, billing hợp lệ, quota còn, và API key được restrict đúng kiểu request. Chỉ cần một mảnh sai, app có thể báo lỗi như bug code dù nguyên nhân thật nằm trong Google Cloud Console.

Các team Việt Nam thường gặp những nhóm lỗi này:

• Billing account không dùng được cho Maps Platform. Có API key nhưng request Maps vẫn fail vì billing không hợp lệ.
• Chưa bật đúng API. Maps JavaScript, Geocoding, Places, Routes là các API riêng.
• Restrict key sai. Domain, server IP, Android package hoặc iOS bundle ID không khớp request thật.
• Hết quota hoặc chạm giới hạn SKU. Dev chạy bình thường, production tăng traffic thì fail.
• Rủi ro hóa đơn. API chạy được nhưng team không muốn treo credit card và lo chi phí tăng bất ngờ.

Nếu sản phẩm chỉ cần tìm kiếm địa chỉ Việt Nam, autocomplete, reverse geocoding hoặc ranh giới hành chính, lượng vận hành này thường quá nặng so với tính năng cần làm.

Khi nào vấn đề này quan trọng

Đừng migrate chỉ vì một request lỗi. Trước tiên cần xác định Google Maps còn đúng với nhu cầu sản phẩm không.

Nên giữ Google Maps nếu bạn cần phủ toàn cầu, Street View, Places quốc tế sâu, hoặc SDK mobile đầy đủ. Google vẫn rất mạnh cho sản phẩm toàn cầu.

Nên cân nhắc giải pháp tập trung Việt Nam nếu nhu cầu chính là:

• Autocomplete địa chỉ ở checkout cho khách Việt Nam.
• Chuyển địa chỉ tiếng Việt thành tọa độ.
• Reverse geocoding vị trí tài xế hoặc khách hàng.
• Xác định tỉnh/huyện từ GPS sau thay đổi hành chính 2025.
• Giữ sản phẩm nhỏ không phụ thuộc credit card và billing phức tạp.

Nếu use case của bạn nằm trong nhóm này, API địa chỉ chuyên Việt Nam sẽ giảm rất nhiều việc vận hành.

Checklist debug nhanh

Hãy bắt đầu bằng request trực tiếp từ server hoặc terminal. Cách này loại bỏ nhiễu từ browser referrer, CORS và framework frontend:

curl "https://maps.googleapis.com/maps/api/geocode/json?address=Ho+Chi+Minh&key=YOUR_KEY"

Sau đó kiểm tra theo thứ tự:

1. Project Google Cloud có đúng project app đang dùng không.
2. Billing đã attach và active cho Maps Platform chưa.
3. API cụ thể đã bật chưa, ví dụ Geocoding hoặc Places.
4. Key restriction có khớp loại request không.
5. Quota/SKU còn đủ không.
6. Backend log có request ra Google không, hay fail trước khi gọi.

Nếu request trực tiếp chạy nhưng app fail, khả năng cao là sai key restriction, domain hoặc env config. Nếu request trực tiếp fail, hãy sửa cấu hình Google Cloud trước khi sửa code.

Cách migrate phần geocoding Việt Nam

Nếu Google quá nặng cho bài toán địa chỉ Việt Nam, hãy migrate từng phần. Geocoding và autocomplete là phần dễ tách nhất.

Trước đây:

const res = await fetch(
  `https://maps.googleapis.com/maps/api/geocode/json?address=${encodeURIComponent(input)}&key=${googleKey}`,
);
const data = await res.json();

Sau khi chuyển:

const res = await fetch(
  `https://api.gogoduk.com/v1/suggest?input=${encodeURIComponent(input)}`,
  { headers: { "X-API-Key": gogodukKey } },
);
const data = await res.json();

Nếu cần mapping field chi tiết, đọc hướng dẫn migrate từ Google Maps Geocoding sang GoGoDuk. Cách rollout an toàn là chạy song song 2 provider trên một tập địa chỉ thật, so sánh kết quả, map response shape, rồi mới đổi production path.

Lỗi triển khai hay gặp

Lỗi lớn nhất là thay toàn bộ Google Maps mà không tách tính năng. Hiển thị bản đồ, autocomplete, reverse geocoding, POI, routing và Street View là các lớp khác nhau. Bạn có thể giữ một provider cho tile map và dùng provider khác cho dữ liệu địa chỉ Việt Nam.

Lỗi thứ hai là chỉ test query quá sạch như "Hanoi" hoặc "Ho Chi Minh City". User thật sẽ gõ thiếu dấu, viết tắt, tên tòa nhà, hẻm/ngõ, hoặc tên phường cũ. Hãy test địa chỉ checkout và delivery thật.

Cuối cùng, đừng hard-code workaround billing vào logic sản phẩm. Nếu billing là điểm nghẽn và traffic chỉ ở Việt Nam, đổi provider geocoding thường sạch hơn.

GoGoDuk phù hợp ở đâu

GoGoDuk tập trung vào geocoding Việt Nam, autocomplete địa chỉ, reverse geocoding và ranh giới hành chính. GoGoDuk không cố thay toàn bộ Google Maps, và đó là chủ đích.

Dùng GoGoDuk khi bạn cần:

• REST API trả JSON đơn giản.
• Free tier không cần credit card.
• Tìm kiếm địa chỉ hiểu dấu tiếng Việt và pattern địa chỉ địa phương.
• Ngữ cảnh tỉnh/huyện cho workflow Việt Nam.

Nếu cần so sánh rộng hơn, đọc Top Map API Việt Nam 2026. Nếu đã biết bạn chỉ cần geocoding, bắt đầu với hướng dẫn migrate hoặc tạo API key miễn phí.

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

Vì sao Google Maps API khó dùng ở Việt Nam? Nhiều team vướng billing, region hoặc cấu hình project trước khi gặp lỗi code thật. Cách sửa phụ thuộc project Google Cloud, billing account và API đang bật.

Có nên thay toàn bộ Google Maps không? Không nhất thiết. Hãy giữ Google nếu bạn cần bản đồ toàn cầu, Street View hoặc Places sâu. Chỉ tách phần geocoding/autocomplete Việt Nam nếu đó là phần gây chi phí hoặc billing pain.

Có dùng GoGoDuk cùng Leaflet hoặc MapLibre được không? Được. Mô hình phổ biến là Leaflet hoặc MapLibre để hiển thị bản đồ, còn GoGoDuk xử lý tìm kiếm địa chỉ, reverse geocoding và dữ liệu hành chính Việt Nam.

Migrate thế nào để không làm hỏng production? Chạy song song 2 provider trên địa chỉ thật, so sánh độ khớp, map response field, rồi chuyển từng endpoint.

Test nhỏ trước

Lấy một địa chỉ Việt Nam thật trong sản phẩm, gọi /v1/suggest, rồi so với kết quả Google hiện tại:

curl -H "X-API-Key: gdk_live_..." \
  "https://api.gogoduk.com/v1/suggest?input=Ben+Thanh+Quan+1"

Đăng ký API key và test những địa chỉ thật sự quan trọng với người dùng của bạn.