Tài liệu API

Đường dẫn, tham số và JSON theo Google Maps Platform. Lấy khoá ở trang chủ, thử trực tiếp ở bảng thử API.

Bắt đầu trong 1 phút

curl "https://geo.mozi.io.vn/maps/api/directions/json?origin=10.7725,106.698&destination=10.8188,106.6588&vehicle=bike&key=KHOA_CUA_BAN"

Khoá gửi qua ?key= (kiểu Google), ?api_key= (kiểu Goong) hoặc header X-Api-Key. Mọi đường đều là GET, trả JSON UTF-8, có CORS để gọi thẳng từ trình duyệt.

Đang dùng Google hoặc Goong?

Đường dẫn, tham số và JSON giống Google Maps Platform. Chỉ cần đổi host:

https://maps.googleapis.com/maps/api/directions/json   →   https://geo.mozi.io.vn/maps/api/directions/json

Thư viện nào cho đặt base URL (hầu hết SDK và wrapper Google Directions/Places) đều dùng được. Xem khác biệt so với Google trước khi chuyển.

Các API

Đường	Tham số	Tương ứng Google
`/maps/api/directions/json`	`origin`, `destination`: `lat,lng` hoặc `place_id:<id>` `waypoints`: tối đa 25, ngăn bằng `\|` `mode`: `driving` \| `two_wheeler` \| `bicycling` \| `walking`, hoặc `vehicle`: `car` \| `bike` \| `taxi` \| `truck` `heading`: hướng xe tại điểm đầu (độ, 0 = Bắc) — tuyến đi tiếp theo chiều xe `language`: `vi` (mặc định) \| `en`	Directions
`/maps/api/distancematrix/json`	`origins`, `destinations` ngăn bằng `\|`, tối đa 625 ô mỗi request; `mode`/`vehicle`	Distance Matrix
`/maps/api/geocode/json`	`address` (+ `location=lat,lng` để ưu tiên vùng) — tìm xuôi, hiểu số nhà và hẻm `latlng` — tìm ngược	Geocoding
`/maps/api/place/autocomplete/json`	`input`, `location`, `radius` (m), `limit` (≤ 20)	Places Autocomplete
`/maps/api/place/details/json`	`place_id` (từ autocomplete hoặc geocode)	Place Details

Ví dụ: Directions

{
  "status": "OK",
  "routes": [{
    "summary": "Trương Định",
    "legs": [{
      "distance": { "value": 7180, "text": "7,2 km" },
      "duration": { "value": 827, "text": "14 phút" },
      "start_location": { "lat": 10.7725, "lng": 106.698 },
      "end_location":   { "lat": 10.8188, "lng": 106.6588 },
      "steps": [{ "distance": {…}, "duration": {…}, "html_instructions": "Rẽ trái  Lê Thánh Tôn",
                  "maneuver": "turn-left", "travel_mode": "TWO_WHEELER", "street_name": "Lê Thánh Tôn" }, …]
    }],
    "overview_polyline": { "points": "ewb`Ao…" },
    "bounds": { "northeast": {…}, "southwest": {…} },
    "geometry": { "type": "LineString", "coordinates": [[106.698, 10.7725], …] }
  }]
}

duration đã hiệu chỉnh cho giao thông đô thị Việt Nam: thời gian của OSRM (giả định đường vắng) nhân hệ số theo loại xe, ô tô 1,62 × + 44 giây, xe máy 1,22 × + 53 giây. Hệ số đo so với ETA thương mại trên 300 cặp điểm TP.HCM (30/09/2026). Quãng đường không đổi.

Ví dụ: Autocomplete

GET /maps/api/place/autocomplete/json?input=cho ben thanh&location=10.77,106.70&key=…

{ "status": "OK", "predictions": [{
    "description": "Chợ Bến Thành, Công trường Quách Thị Trang, Phường Bến Thành, Thành phố Hồ Chí Minh",
    "place_id": "W39514795",
    "structured_formatting": { "main_text": "Chợ Bến Thành", "secondary_text": "Công trường Quách Thị Trang, Phường Bến Thành, …" },
    "location": { "lat": 10.7725301, "lng": 106.6980365 },
    "old_address": "Công trường Quách Thị Trang, Phường Bến Thành, Quận 1, Thành phố Hồ Chí Minh",
    "distance_meters": 354,
    "pickup_points": [ { "name": "Cổng Lê Lợi", "lat": …, "lng": …, "vehicle": "all" } ]
}] }

Khác biệt so với Google

Có thêm

location ngay trong gợi ý autocomplete — không cần gọi Place Details chỉ để lấy toạ độ.
old_address: địa chỉ theo đơn vị hành chính trước 1/7/2025, cho hệ thống còn lưu địa chỉ cũ.
pickup_points: điểm đón/trả bên trong sân bay, bệnh viện, trường, chung cư.
geometry GeoJSON cạnh overview_polyline, street_name từng bước, heading khi tìm lại đường.
Số nhà và hẻm trong geocode: "278 Dương Quảng Hàm", "80/12/89 …".

Chưa có / khác

Điểm đi/đến chỉ nhận lat,lng hoặc place_id:…, không nhận chuỗi địa chỉ (gọi geocode trước).
Một leg cho cả chuyến dù có waypoints; bước đi không có toạ độ riêng.
Không mode=transit, không tối ưu thứ tự waypoints, không traffic theo giờ.
Lỗi trả mã HTTP thật (400/401/429/503) thay vì luôn 200 như Google — xem dưới.
Chỉ phủ Việt Nam (kể cả Hoàng Sa, Trường Sa).

Lỗi và hạn mức

`status`	HTTP	Khi nào
`OK` / `ZERO_RESULTS` / `NOT_FOUND`	200	Trả lời hợp lệ (không có tuyến, không có kết quả, place_id không tồn tại)
`INVALID_REQUEST`	400	Thiếu hoặc sai tham số — `error_message` nói rõ
`REQUEST_DENIED`	401 / 403	Thiếu, sai hoặc đã tắt khoá; khoá trình duyệt gọi từ website chưa đăng ký
`OVER_QUERY_LIMIT`	429	Quá hạn mức phút hoặc tháng của khoá, hoặc quá 30 request/giây từ một IP. Có `Retry-After`
`UNKNOWN_ERROR`	503	Máy chủ tạm lỗi — thử lại sau vài giây

Mỗi trả lời mang X-RateLimit-Limit, X-RateLimit-Remaining (phút) và X-Quota-Remaining (tháng; -1 = không giới hạn). Request trả 5xx không tính vào hạn mức.

Gói và giá giá giới thiệu

Giá tính bằng đồng vì dịch vụ chỉ phủ Việt Nam. 50.000 request đầu mỗi tháng miễn phí, phần vượt tính theo 1.000 request. Máy tính chi phí và so sánh với Goong, Google ở trang chủ.

API	đ / 1.000 request
Autocomplete (`place/autocomplete`)	18.000
Toạ độ ra địa chỉ (`geocode?latlng=`)	18.000
Chỉ đường, ma trận (`directions`, `distancematrix`)	30.000
Địa chỉ ra toạ độ (`geocode?address=`)	38.000
Chi tiết địa điểm (`place/details`)	50.000

Khối lượng lớn, cam kết thời gian hoạt động, máy chủ riêng hoặc dữ liệu theo yêu cầu: liên hệ. Hoá đơn theo tháng, thanh toán chuyển khoản, có hoá đơn điện tử.

Điều khoản và ghi công

Dữ liệu chỉ được dùng qua API, trong ứng dụng của bạn. Không lưu trữ hàng loạt, không trích xuất để xây cơ sở dữ liệu riêng, không bán lại hoặc phân phối lại kết quả.
Khoá là của bạn: không chia sẻ công khai; khoá dùng trong trình duyệt nên đăng ký website để được chặn theo nguồn.
Bản đồ và dữ liệu tuân thủ pháp luật Việt Nam về thể hiện chủ quyền (Hoàng Sa, Trường Sa).
Ghi công khi hiển thị dữ liệu: © OpenStreetMap contributors (ODbL), © Overture Maps Foundation, Foursquare OS Places.
Dịch vụ cung cấp "như hiện có"; gói FREE không kèm cam kết thời gian hoạt động.