Chuyển tới nội dung chính

Dịch Vụ Vị Trí và Chuyến Đi

Trang này giải thích cách truy xuất vị trí phương tiện và lịch sử chuyến đi bằng Fleet API cho cả nhóm nghiệp vụ và kỹ thuật.

Từ Viết Tắt và Thuật Ngữ​

  • API: Giao diện Lập trình Ứng dụng.
  • GPS: Hệ thống Định vị Toàn cầu.

Nên Dùng Endpoint Nào?​

Dùng mapping sau khi khách hàng yêu cầu dữ liệu liên quan đến vị trí:

1) Toàn Bộ Vị Trí GPS​

Ý Nghĩa​

Truy xuất các sự kiện vị trí lịch sử trong một khoảng thời gian để dựng lại phương tiện đã di chuyển ở đâu.

Endpoint Phù Hợp Nhất​

Diễn Giải Theo Nghiệp Vụ​

  • Dùng cho điều tra, trip replay, chứng minh hiện diện và kiểm tra vận hành.
  • Là nguồn phù hợp nhất khi người dùng yêu cầu "toàn bộ điểm" trong một khung thời gian.

Diễn Giải Cho Developer​

  • Xử lý events như các điểm telemety lịch sử.
  • Thực hiện query theo cửa sổ thời gian và phân trang khi cần.
  • Với giai đoạn dài, nên fetch theo từng phần để tránh response quá lớn.

2) Theo Dõi Liên Tục (Near Real-Time)​

Ý Nghĩa​

Hiển thị liên tục vị trí gần nhất đã biết của phương tiện, tương tự bản đồ đội xe live.

Endpoint Phù Hợp Nhất​

Diễn Giải Theo Nghiệp Vụ​

  • Dùng cho vận hành hằng ngày theo thời gian thực và giám sát điều phối.
  • Phù hợp nhất cho use case "phương tiện đang ở đâu ngay bây giờ?".

Diễn Giải Cho Developer​

  • Triển khai polling (ví dụ mỗi 10 đến 30 giây) để làm mới trạng thái mới nhất.
  • Đây là polling trạng thái near real-time, không phải websocket streaming feed.
  • Kết hợp với endpoint events khi cần chi tiết breadcrumb lịch sử.

3) Lịch Sử Chuyến Đi Đầy Đủ​

Ý Nghĩa​

Tùy theo mục tiêu của khách hàng, "lịch sử chuyến đi" có thể có nghĩa là:

  • Các điểm breadcrumb đầy đủ của một hành trình, hoặc
  • Bản tóm tắt chuyến đi với điểm bắt đầu và kết thúc.

Lựa Chọn Endpoint​

  • Với điểm breadcrumb đầy đủ của chuyến đi: dùng endpoint events.
  • Với vị trí bắt đầu và kết thúc ở cấp độ chuyến đi:

Diễn Giải Theo Nghiệp Vụ​

  • Dùng trips cho báo cáo và phân tích KPI ở cấp độ chuyến đi.
  • Dùng events khi nhà phân tích cần chi tiết ở cấp độ quỹ đạo.

Diễn Giải Cho Developer​

  • Trips là bản ghi tóm tắt, không nên xem là dataset đầy đủ điểm chuyến đi.
  • Dựng trip replay đầy đủ từ dữ liệu events trong khoảng thời gian đã chọn.

Mẫu Triển Khai Khuyến Nghị​

Với đa số ứng dụng quản lý đội xe:

  1. Poll endpoint trạng thái phương tiện để lấy trạng thái hiện tại trên bản đồ.
  2. Query endpoint events để phát lại lộ trình lịch sử.
  3. Query endpoint trips cho báo cáo chuyến đi (điểm đầu/cuối và ngữ cảnh chuyến đi).