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, tối ưu cho hệ thống dữ liệu lớn.

🔒 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://mapapi.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://mapapi.odsbase.com/v1/map

2.1. Autocomplete & Forward Geocoding (Tìm kiếm thông minh tích hợp AI)

API được hỗ trợ bởi bộ não AI NLP (Libpostal), cung cấp tính năng tự động gợi ý địa điểm theo thời gian thực. Hệ thống tự động bóc tách số nhà và tên đường (VD: "23 Phạm") để tìm kiếm chính xác mà không cần truyền riêng biệt.

Endpoint: GET /autocomplete

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

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: 23 Phạm Thị Kỳ).
`lat`	float	Không	Vĩ độ hiện tại. Khi kết hợp với `lon`, hệ thống sẽ ưu tiên tìm trong bán kính 2000km.
`lon`	float	Không	Kinh độ hiện tại.
`type`	string	Không	Lọc kết quả theo danh mục (category). VD: `poi`, `road`.

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

{
  "status": "success",
  "data": [
    {
      "id": "map:poi:5e23676d-d881-45d9-8a66",
      "name": "Chợ Bến Thành",
      "category": "poi",
      "location": "106.6980,10.7725"
    }
  ]
}

2.2. 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 điểm gần nhất (tự động quét bán kính 1km).

Endpoint: GET /reverse

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

Tham số URL bổ sung:

type (Không bắt buộc): Chỉ trả về địa điểm thuộc loại được chỉ định.

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Đ