Tài Liệu API ODSBase Map

TÀI LIỆU TÍCH HỢP ODSBASE MAP API

Bản đồ ODSBase cung cấp giao diện lập trình ứng dụng (API) phục vụ cho các ứng dụng cần tính năng bản đồ thay thế cho Google Map

🔒 1. Xác thực & Bảo mật (Authentication & Security)

Lưu ý quan trọng: Hệ thống ODSBase Map API áp dụng cơ chế bảo mật trên header. Tất cả các yêu cầu gửi đến API đều phải bao gồm Token xác thực và Header định danh nền tảng (Client Identifier). Nếu thiếu hoặc thông tin không khớp với cấu hình đã được cấp, hệ thống sẽ từ chối truy cập (HTTP 401 hoặc 403).

1.1. Token Xác thực (Bắt buộc cho mọi nền tảng)

API Key không được truyền trực tiếp trên URL mà được đính kèm qua HTTP Header chuẩn Authorization:

Key: Authorization
Value: Bearer YOUR_API_KEY_HERE

1.2. Định danh Nền tảng (Client Identifier Headers)

Tùy thuộc vào nền tảng ứng dụng (Web, iOS, hoặc Android), client bắt buộc phải truyền thêm các Header tương ứng để hệ thống xác minh và thống kê .

Nền tảng	Header Bắt buộc	Mô tả / Ví dụ
Web / Browser	`Origin` hoặc `Referer`	Trình duyệt sẽ tự động đính kèm. Khớp với danh sách Domain được phép. VD: https://odsbase.com
iOS App	`X-Ios-Bundle-Identifier`	Định danh Bundle ID của ứng dụng iOS. VD: com.odsbase.superapp
Android App	`X-Android-Package`	Định danh Package ID của ứng dụng Android. VD: com.odsbase.driver
Android App	`X-Android-Cert`	Mã băm SHA-1 của Keystore dùng để build App (Chống giả mạo Package). VD: BB:0D:AC:74:D3:21:E1...

Ví dụ gọi API bằng cURL (Dành cho App Android):

curl -X GET "https://apimap.odsbase.com/v1/map/autocomplete?q=Chợ%20Bến" \
     -H "Authorization: Bearer YOUR_API_KEY_HERE" \
     -H "X-Android-Package: com.odsbase.driver" \
     -H "X-Android-Cert: BB:0D:AC:74:D3:21..."

2. GEOCODING API (Tìm kiếm Địa điểm)

Base URL: https://apimap.odsbase.com/v1/map

2.1. Autocomplete (Gợi ý thông minh)

API cung cấp tính năng tự động điền và gợi ý địa điểm theo thời gian thực khi người dùng đang gõ phím. Hỗ trợ lọc theo vị trí hiện tại để ưu tiên kết quả gần nhất.

Endpoint: GET /autocomplete

Request URL:
https://apimap.odsbase.com/v1/map/autocomplete?q={keyword}&lat={lat}&lon={lon}&radius={radius}

Tham số URL (Query Parameters):

Tham số	Loại	Bắt buộc	Mô tả
`q`	string	Có	Từ khóa tìm kiếm (VD: Chợ Bến T).
`lat`	float	Không	Vĩ độ của người dùng (dùng để ưu tiên kết quả gần nhất).
`lon`	float	Không	Kinh độ của người dùng.
`radius`	int	Không	Bán kính tìm kiếm (tính bằng km). Mặc định là `50`.

JSON Phản hồi thành công (200 OK):

{
  "status": "success",
  "data": [
    {
      "id": "poi:10234",
      "name": "Chợ Bến Thành",
      "address": "Lê Lợi, Phường Bến Thành, Quận 1, TP.HCM",
      "lat": "10.7725",
      "lon": "106.6980"
    }
  ]
}

2.2. Forward Geocoding (Chuyển đổi địa chỉ sang tọa độ)

Sử dụng để tìm kiếm tọa độ chính xác của một địa chỉ đầy đủ hoặc một địa danh cụ thể.

Endpoint: GET /forward

Request URL:
https://apimap.odsbase.com/v1/map/forward?q={address}

2.3. Reverse Geocoding (Chuyển đổi tọa độ sang địa chỉ)

Thường được App Mobile gọi khi khách hàng di chuyển ghim (pin) trên bản đồ để lấy tên đường/địa chỉ tại điểm đó.

Endpoint: GET /reverse

Request URL:
https://apimap.odsbase.com/v1/map/reverse?lat={lat}&lon={lon}&radius={radius}

Tham số URL bổ sung:

radius (Không bắt buộc): Bán kính quét tìm đường/tòa nhà gần nhất (mặc định 2km).

3. ROUTING API (Định tuyến & Dẫn đường)

Base URL: https://osrmmap.odsbase.com

API hỗ trợ các phép tính toán định tuyến đường bộ.
Lưu ý: Hệ tọa độ luôn theo chuẩn {longitude},{latitude} (Kinh độ trước, Vĩ độ sau).

3.1. Route Service (Tìm đường cơ bản)

Tìm đường đi ngắn nhất hoặc nhanh nhất giữa 2 hoặc nhiều tọa độ.

Endpoint: GET /route/v1/driving/{coordinates}

Request URL:
https://osrmmap.odsbase.com/route/v1/driving/106.698,10.772;106.721,10.732?steps=true&overview=full

Tham số URL (Query Parameters):

Tham số	Loại	Bắt buộc	Mô tả
`coordinates`	string	Có	Danh sách tọa độ cách nhau bởi dấu chấm phẩy `;` (VD: `lon1,lat1;lon2,lat2`).
`steps`	boolean	Không	Trả về hướng dẫn chi tiết từng ngã rẽ (`true` hoặc `false`).
`overview`	string	Không	Độ chi tiết của đường vẽ (`full`, `simplified`, hoặc `false`).

JSON Phản hồi thành công (200 OK):

{
  "code": "Ok",
  "routes": [
    {
      "distance": 5430.5, 
      "duration": 1245.2, 
      "geometry": "w~_pA..._@}B",
      "legs": [...]
    }
  ],
  "waypoints": [...]
}

3.2. Table Service (Ma trận khoảng cách - Matrix)

Sử dụng thuật toán cực nhanh để tính toán khoảng cách và thời gian (ETA) từ nhiều điểm xuất phát đến nhiều điểm đến. API cốt lõi để "Tìm tài xế gần nhất", "Tìm các địa điểm gần nhất"

Endpoint: GET /table/v1/driving/{coordinates}

Request URL:
https://osrmmap.odsbase.com/table/v1/driving/{lon1,lat1};{lon2,lat2};{lon3,lat3}?sources=0,1&destinations=2

4. MAP DATA API (Máy chủ Bản đồ Vector)

Base URL: https://mapdata.odsbase.com

API này được các thư viện Frontend (Mapbox GL JS, MapLibre, Flutter Map) gọi để kết xuất bản đồ lên màn hình.

4.1. Vector Tiles (Dữ liệu mảnh bản đồ)

Truy xuất dữ liệu hình học của đường xá, tòa nhà theo từng mức zoom (z) và tọa độ khung (x, y).

Endpoint: GET /{source}/{z}/{x}/{y}.pbf

Request URL:
https://mapdata.odsbase.com/public.vietnam_places/14/13014/7612.pbf

4.2. Fonts / Glyphs (Ký tự hiển thị)

Cung cấp các bộ font chữ PBF để render tên đường, tên địa điểm.

Endpoint: GET /font/{fontstack}/{range}.pbf

Request URL:
https://mapdata.odsbase.com/font/Noto%20Sans%20Regular/0-255.pbf

4.3. Catalog (Danh mục)

Khám phá danh sách tất cả các lớp bản đồ (Sources) hiện đang có sẵn trên hệ thống ODSBase.

Endpoint: GET /catalog

Request URL:
https://mapdata.odsbase.com/catalog

Giỏ hàng

Tổng phụ: 0VNĐ

Tổng cộng: 0VNĐ