F Location is a comprehensive location tracking application built on Frappe framework, designed to track real-time locations of Customers, Employees, and Suppliers with interactive map visualization.
- Dynamic Reference Support: Track locations for Customers, Employees, or Suppliers using dynamic links
- Real-time Location Tracking: Enable/disable location tracking per user with checkbox control
- Current & Target Locations: Store both current position and target destination coordinates
- Interactive Map View: Web-based map interface powered by Leaflet.js
- Route Visualization: Display route between current location and target when both are provided
- User Details on Hover: View summary information by hovering over map markers
- Flexible Display Names: Custom display names for easy identification
- Geolocation Support: Built-in browser geolocation integration for easy location updates
- Socket.IO Integration: Real-time location updates using Frappe's Socket.IO with Redis backend
- Live Map Updates: Map markers update automatically when locations change
- Broadcast Updates: Location changes are pushed to all connected clients instantly
- Background Workers: Scheduled tasks for periodic location broadcasting and stale location checks
- Dedicated Mobile Page: Mobile-optimized page at
/share-locationfor continuous location sharing - Configurable Update Interval: Adjust update frequency from 10 seconds to 5 minutes
- High Accuracy GPS: Toggle high-accuracy mode for better location precision
- Keep Screen On: Wake Lock API support to prevent screen from sleeping during tracking
- Battery Efficient: Optimized for mobile devices with configurable update intervals
- Historical Tracking: Automatically save all location updates with timestamps
- Track Movement Paths: View historical routes and movement patterns
- Detailed Metrics: Store accuracy, altitude, speed, and heading information
- Data Retention: Configurable cleanup of old location history records
- Virtual Boundaries: Create circular geofences around specific locations
- Entry/Exit Detection: Automatic detection when trackers enter or exit geofences
- Smart Notifications: Email and in-app notifications for geofence events
- Custom Alerts: Configure separate notifications for entry and exit events
- Multiple Geofences: Support for multiple geofences per location tracker
- REST API: Complete RESTful API for mobile app integration
- Batch Updates: Support for batch location updates to reduce API calls
- GPS Metadata: Track accuracy, altitude, speed, and heading from GPS devices
- Nearby Search: Find trackers within a specified radius
- Quick Tracker Creation: API endpoint for programmatic tracker creation
The main DocType for tracking user locations:
- Enable Location Tracking: Checkbox to enable/disable tracking
- Reference Type: Link to DocType (Customer/Employee/Supplier)
- Reference Name: Dynamic link to the selected reference type
- Display Name: Custom name for display purposes
- Current Latitude/Longitude: Current location coordinates
- Target Latitude/Longitude: Target destination coordinates (optional)
- Summary Details: Additional information displayed in map popups
Automatically tracks historical location data:
- Location Tracker: Link to Location Tracker
- Latitude/Longitude: Location coordinates
- Timestamp: When location was recorded
- Accuracy: GPS accuracy in meters
- Altitude: Altitude in meters
- Speed: Speed in m/s
- Heading: Direction in degrees
- Recorded By: User who recorded the location
Define virtual boundaries and trigger alerts:
- Geofence Name: Unique name for the geofence
- Type: Circular (polygon support coming soon)
- Location Tracker: Optional link to specific tracker
- Center Latitude/Longitude: Center point of circular geofence
- Radius: Radius in meters
- Notify on Entry/Exit: Toggle notifications
- Notification Emails: Comma-separated email addresses
- Notification Users: Comma-separated usernames for in-app alerts
Interactive map for viewing all tracked locations:
- View all tracked users on a single map
- Select individual users to view their location and route
- See target routes when destination coordinates are provided
- Hover over markers to view user summary details
- Real-time updates via WebSocket (no manual refresh needed)
- Automatic marker animation when locations update
Mobile-optimized page for sharing your location:
- Select your location tracker
- Start/stop location sharing with one tap
- Configure update interval (10s - 5 minutes)
- Toggle high-accuracy GPS mode
- Keep screen on during tracking
- View real-time statistics (coordinates, accuracy, update count)
- Battery-efficient with configurable intervals
You can install this app using the bench CLI:
cd $PATH_TO_YOUR_BENCH
bench get-app $URL_OF_THIS_REPO --branch develop
bench install-app f_location- Navigate to Location Tracker list
- Create a new Location Tracker
- Select Reference Type (Customer, Employee, or Supplier)
- Select the specific reference (e.g., a specific customer)
- Enter a Display Name
- Check "Enable Location Tracking"
- Use "Get Current Location" button to auto-fill coordinates
- Optionally add Target Latitude/Longitude for destination
- Add Summary Details for additional information
- Access the map at
/location-mapor click "View on Map" from any Location Tracker - Use the dropdown to select a specific user or view all users
- Click markers to see popup with user details
- When target location is set, a route line will be displayed
- Real-time updates appear automatically (no refresh needed)
- Visit
/share-locationon your mobile device - Select your tracker from the dropdown
- Click "Start Sharing Location"
- Adjust update interval as needed
- The app will continuously send your GPS location to the server
- Create a new Geofence document
- Enter a name and select "Circular" type
- Set center coordinates (latitude/longitude)
- Define radius in meters
- Optionally link to specific Location Tracker
- Enable "Notify on Entry" and/or "Notify on Exit"
- Add notification emails or usernames
- When a tracker enters/exits the geofence, alerts will be sent automatically
- Open any Location Tracker
- View linked Location History records
- Filter by date range to see movement patterns
- Export historical data for analysis
Returns all enabled location trackers with their current positions.
frappe.call({
method: 'f_location.f_location.doctype.location_tracker.location_tracker.get_all_locations',
callback: function(r) {
console.log(r.message);
}
});Get detailed location information for a specific tracker.
frappe.call({
method: 'f_location.f_location.doctype.location_tracker.location_tracker.get_location',
args: { tracker_name: 'John Doe' },
callback: function(r) {
console.log(r.message);
}
});Update the current location of a tracker (basic method).
frappe.call({
method: 'f_location.f_location.doctype.location_tracker.location_tracker.update_current_location',
args: {
tracker_name: 'John Doe',
latitude: 28.6139,
longitude: 77.2090
}
});Advanced location update with GPS metadata and geofence checking.
frappe.call({
method: 'f_location.api.update_location_from_mobile',
args: {
location_tracker: 'John Doe',
latitude: 28.6139,
longitude: 77.2090,
accuracy: 10.5,
altitude: 250.0,
speed: 5.2,
heading: 180.0
},
callback: function(r) {
if (r.message.success) {
console.log('Geofences:', r.message.geofences);
}
}
});Update multiple locations in a single API call.
frappe.call({
method: 'f_location.api.batch_update_locations',
args: {
updates: [
{ location_tracker: 'Tracker 1', latitude: 28.6139, longitude: 77.2090 },
{ location_tracker: 'Tracker 2', latitude: 19.0760, longitude: 72.8777 }
]
}
});Find all trackers within a specified radius.
frappe.call({
method: 'f_location.api.get_nearby_trackers',
args: {
latitude: 28.6139,
longitude: 77.2090,
radius_km: 10
},
callback: function(r) {
console.log('Nearby trackers:', r.message);
}
});Get detailed status including last update time and GPS metrics.
frappe.call({
method: 'f_location.api.get_tracker_status',
args: { location_tracker: 'John Doe' }
});Quickly create a new location tracker programmatically.
frappe.call({
method: 'f_location.api.create_location_tracker_quick',
args: {
reference_type: 'Employee',
reference_name: 'EMP-001',
display_name: 'John Doe',
auto_enable: true
}
});Retrieve historical location data.
frappe.call({
method: 'f_location.f_location.doctype.location_history.location_history.get_location_history',
args: {
location_tracker: 'John Doe',
limit: 100,
from_date: '2025-01-01',
to_date: '2025-01-31'
}
});Get location path coordinates for drawing routes on maps.
frappe.call({
method: 'f_location.f_location.doctype.location_history.location_history.get_location_path',
args: { location_tracker: 'John Doe' },
callback: function(r) {
// Returns array of [lat, lng] coordinates
var path = L.polyline(r.message, {color: 'blue'}).addTo(map);
}
});Get all geofences for map visualization.
frappe.call({
method: 'f_location.f_location.doctype.geofence.geofence.get_geofences_for_map',
callback: function(r) {
r.message.forEach(function(geofence) {
// Draw geofence circles on map
L.circle([geofence.center_latitude, geofence.center_longitude], {
radius: geofence.radius_meters
}).addTo(map);
});
}
});The application uses Frappe's Socket.IO with Redis for real-time updates. Subscribe to these events:
Triggered when any location tracker is updated.
frappe.realtime.on('location_update', function(data) {
console.log('Location updated:', data.display_name);
// Update UI with new location
});Triggered when a tracker enters or exits a geofence.
frappe.realtime.on('geofence_alert', function(data) {
console.log('Geofence event:', data.event_type);
frappe.show_alert({
message: data.subject,
indicator: 'orange'
});
});The following scheduled tasks run automatically:
- Every 5 minutes: Broadcast all current locations to connected clients
- Hourly: Check for stale location trackers (no update in 2+ hours)
- Daily: Clean up old location history records (default: 90 days retention)
Configure retention period in System Settings or modify in tasks.py.
This app uses pre-commit for code formatting and linting. Please install pre-commit and enable it for this repository:
cd apps/f_location
pre-commit installPre-commit is configured to use the following tools for checking and formatting your code:
- ruff
- eslint
- prettier
- pyupgrade
gpl-3.0