Logistics Tracking Utilities and Geofence Monitoring

Overview

This module provides the core utility functions used by the logistics tracking system. It includes functionality for:

Geofence detection
Vehicle location tracking
Route generation using Mapbox
ETA calculation
Address location management
Telemetry processing
Vehicle geofence alert logging

These utilities support the logistics fleet tracking system by enabling real-time monitoring of vehicle movement and operational analytics.

1. Date Conversion Utility

Function

convert_to_yyyy_mm_dd(datetime_str)

Purpose

Converts a datetime string from the format:

DD-MM-YYYY HH:MM:SS

to the standard database format:

YYYY-MM-DD HH:MM:SS

Example

Input: 14-02-2026 10:25:30
Output: 2026-02-14 10:25:30

2. Logistics Settings Cache

Function

get_logistics_settings_page()

Purpose

Fetches and caches the Logistics Settings document and metadata to reduce database queries.

Cache Duration

5 minutes (300 seconds)

Cached Items

Logistics Settings document
Logistics Settings metadata

3. Distance Calculation (Haversine)

Function

haversine(lon1, lat1, lon2, lat2)

Purpose

Calculates the great-circle distance between two geographic coordinates.

Output

Distance in meters.

Formula

The haversine formula accounts for Earth's curvature when computing distance.

4. Bounding Box Generator

Function

get_bounding_box(lat, lng, radius_km)

Purpose

Creates a bounding box around a location using latitude and longitude.

Use Cases

Spatial queries
Geofence filtering
Map search optimization

5. Geofence Detection

Main Function

is_point_inside_geofence()

Supported Geofence Types

Type	Description
Polygon	Multi-point boundary area
Point + Radius	Circular geofence

Sub Functions

is_point_inside_polygon()
is_point_inside_circle()

Libraries Used

Shapely (geometry calculations)
Haversine distance formula

6. Logistics Tracking Information

Function

get_logistics_tracking_details(tracking_id)

Purpose

Fetches basic tracking information from the Logistics Tracking document.

Returned Fields

Vehicle
Expected Start Time
Expected End Time

7. Route Generation (Mapbox)

API Function

get_route(pickup_lat, pickup_lng, delivery_lat, delivery_lng)

Purpose

Fetches the optimal driving route between two locations using the Mapbox Directions API.

API Endpoint

https://api.mapbox.com/directions/v5/mapbox/driving/

Returned Data

Route geometry
Total distance
Estimated duration

Caching

Route responses are cached for 5 minutes to reduce API calls.

8. ETA Calculation

Function

calculate_eta()

Purpose

Calculates estimated arrival time based on route distance and duration.

Output

{
  "eta_distance_km": 52.4,
  "eta_duration_hours": 1.6
}

Optional Format

Human readable duration:

1 hr 35 mins

9. Threshold Configuration

Function

fetch_threshold_constants()

Purpose

Retrieves operational thresholds from Logistics Settings.

Threshold Types

Threshold	Description
STOP_THRESHOLD_SEC	Minimum time for vehicle stoppage detection
DEVIATION_THRESHOLD_M	Maximum allowed route deviation
PICKUP_THRESHOLD_M	Pickup arrival detection radius
DESTINATION_THRESHOLD_M	Destination arrival detection radius
GEOFENCE_RADIUS_M	Default geofence radius
SPEED_THRESHOLD	Vehicle speed alert threshold
TRIP_DELAY_ALERT	Delay alert trigger threshold

10. Address Location Query

Function

get_address_details_based_on_type()

Purpose

Fetches address records with valid coordinates and location metadata.

Filters

Latitude available
Longitude available
Geofence data available
Address not disabled

Supported Address Types

Plant
Warehouse
Parking
Office
Shop

11. Timestamp Range Validation

Function

is_timestamp_within_range()

Purpose

Checks if a timestamp falls within a specified time window.

Algorithm

Binary search using bisect
Time comparison within ± window

12. Vehicle Telemetry

Function

get_vehicle_location(vehicle)

Purpose

Fetches the latest GPS telemetry for a vehicle.

Data Source

Vehicle Tracking Connector Service API.

Returned Data

Latitude
Longitude
Timestamp

13. Assigned Vehicle Status

Function

get_assigned_vehicles_by_status()

Purpose

Returns vehicle trip assignment status for logistics tracking.

Status Mapping

Logistics Status	Assignment Status
Started	Started
Other	Not Started

14. JSON File Attachment

Function

attach_json_file()

Purpose

Attaches JSON telemetry or debugging data to a document file.

Storage Location

Home/Telemetry_Attachment

15. Latitude / Longitude Parser

Function

process_lat_lng_value()

Purpose

Converts coordinate formats into decimal degrees.

Supported Formats

Decimal Degrees (DD)
Degrees Minutes (DMM)
Degrees Minutes Seconds (DMS)

16. Vehicle Geofence Monitoring

Function

validate_vehicle_geofence_tracking()

Purpose

Checks vehicle positions against configured geofences and logs entry or exit events.

Workflow

Fetch all active vehicles
Fetch configured geofences
Retrieve vehicle telemetry
Check if vehicle is inside geofence
Detect state changes
Create geofence alert log

17. Geofence Alert Logging

Function

create_geofence_vehicle_alert_log()

Purpose

Creates logs whenever a vehicle enters or exits a geofence.

Movement Types

In
Out

Logged Fields

Vehicle
Geofence ID
Timestamp
Latitude
Longitude
Movement Type

18. Role-Based Data Access

Function

get_permission_query_conditions()

Purpose

Restricts geofence alert logs based on fleet manager roles.

Role Mapping

Role	Vehicle Type
Block Fleet Manager	Block
AAC Fleet Manager	AAC
RMC Fleet Manager	RMC

Users can only access logs related to their assigned vehicle type.

Conclusion

This module forms the foundation of the logistics fleet tracking system. It provides utilities for route computation, geofence monitoring, vehicle telemetry analysis, and operational alerts that enable real-time logistics visibility and fleet management.