Positions and Route Services
หน้านี้อธิบายวิธีดึงข้อมูลตำแหน่งรถและประวัติเส้นทางด้วย Fleet API สำหรับทั้งผู้ใช้งานเชิงธุรกิจและผู้พัฒนา
Acronyms and Terms
- API: Application Programming Interface
- GPS: Global Positioning System
Which Endpoint Should I Use?
ใช้ mapping นี้เมื่อลูกค้าต้องการข้อมูลด้านตำแหน่ง:
- All GPS positions / full route point history:
- Continuous tracking (near real-time fleet view):
- Trip start and end locations:
1) All GPS Positions
What It Means
ดึง historical position events ตามช่วงเวลา เพื่อสร้างภาพว่าแต่ละรถเคยอยู่ที่ใดบ้าง
Best Endpoints
- รถหนึ่งคัน: Get events for one vehicle
- ทุกคัน: Get events for all vehicles
Business Interpretation
- เหมาะกับงานตรวจสอบย้อนหลัง route replay, proof of presence และการ audit การปฏิบัติงาน
- เป็นแหล่งข้อมูลหลักเมื่อผู้ใช้ต้องการ "ทุกจุด" ในช่วงเวลาที่กำหนด
Developer Interpretation
- ควรมอง events เป็น historical telemetry points
- ควร query เป็น time windows และทำ pagination ตามเหมาะสม
- สำหรับช่วงเวลายาว ควรดึงข้อมูลเป็นช่วงย่อยเพื่อลดขนาด response
2) Continuous Tracking (Near Real-Time)
What It Means
แสดงตำแหน่งล่าสุดที่ทราบของรถอย่างต่อเนื่อง คล้าย live fleet map
Best Endpoint
Business Interpretation
- เหมาะสำหรับการปฏิบัติงานประจำวันแบบ real-time และการมอนิเตอร์โดยทีม dispatch
- เหมาะกับ use case แบบ "รถอยู่ที่ไหนตอนนี้"
Developer Interpretation
- ใช้ polling (เช่น ทุก 10-30 วินาที) เพื่อรีเฟรชสถานะล่าสุด
- นี่คือ near real-time status polling ไม่ใช่ websocket streaming
- ควรใช้ร่วมกับ events endpoints หากต้องการ historical breadcrumb detail
3) Full Route History
What It Means
ตามบริบทของลูกค้า "route history" อาจหมายถึง:
- จุด breadcrumb ครบตลอดเส้นทางของการเดินทาง หรือ
- สรุประดับทริปที่มีจุดเริ่มต้นและสิ้นสุด
Endpoint Selection
- ถ้าต้องการ full breadcrumb route points: ใช้ events endpoints
- ถ้าต้องการ trip-level start and end locations:
Business Interpretation
- ใช้ trips สำหรับ reporting และการวิเคราะห์ KPI ระดับทริป
- ใช้ events เมื่อต้องการรายละเอียดระดับเส้นทางจริง
Developer Interpretation
- Trips เป็น summary records ไม่ใช่ชุดข้อมูล route points แบบครบถ้วน
- การทำ full route replay ควรสร้างจากข้อมูล events ในช่วงเวลาที่เลือก
Recommended Implementation Pattern
สำหรับแอปพลิเคชันฟลีทส่วนใหญ่:
- Poll vehicle status endpoint เพื่ออัปเดตสถานะบนแผนที่ปัจจุบัน
- Query events endpoints เพื่อเล่นเส้นทางย้อนหลัง
- Query trips endpoints เพื่อทำรายงานทริป (จุดเริ่มต้น/สิ้นสุด และบริบทของทริป)