[Locus Logo]

Locus

A battle-tested background geolocation SDK for Flutter.
High-performance tracking, motion recognition, geofencing, and automated sync for Android and iOS.

Key Features #

• Continuous Tracking: Reliable background updates with adaptive filters.
• Motion Recognition: Activity detection (walking, running, driving, stationary).
• Geofencing: Circular and polygon geofences with enter/exit/dwell detection.
• Polygon Geofences: Define complex boundaries with arbitrary shapes.
• Geofence Workflows: Multi-step geofence sequences with timeouts.
• Privacy Zones: Exclude, obfuscate, or reduce accuracy in sensitive areas.
• Trip Detection: Automatic trip start/end detection with route recording.
• Battery Optimization: Adaptive profiles based on speed, activity, and battery level.
• Automated Sync: HTTP synchronization with retry logic and batching.
• Offline Reliability: SQLite persistence to prevent data loss.
• Headless Execution: Execute background logic even when the app is terminated.

Documentation #

For full documentation, visit locus.dev or check the local docs folder:

• Quick Start - Get running in 5 minutes.
• Architecture - Project structure and design.
• Configuration - Configuration options and presets.
• Geofencing - Circular and polygon geofences.
• Privacy Zones - Location privacy features.
• Trip Tracking - Trip detection and recording.
• Battery Optimization - Adaptive tracking.
• Platform Setup - iOS & Android permissions.

Quick Start #

1. Installation #

dependencies:
  locus: ^1.1.0

2. Basic Setup #

import 'package:locus/locus.dart';

void main() async {
  // 1. Initialize
  await Locus.ready(Config.balanced(
    url: 'https://api.yourservice.com/locations',
  ));

  // 2. Start tracking
  await Locus.start();

  // 3. Listen to updates
  Locus.onLocation((location) {
    print('Location: ${location.coords.latitude}, ${location.coords.longitude}');
  });
}

3. Add Geofences #

// Circular geofence
await Locus.addGeofence(Geofence(
  identifier: 'office',
  latitude: 37.7749,
  longitude: -122.4194,
  radius: 100,
  notifyOnEntry: true,
  notifyOnExit: true,
));

// Polygon geofence
await Locus.addPolygonGeofence(PolygonGeofence(
  identifier: 'campus',
  vertices: [
    GeoPoint(latitude: 37.7749, longitude: -122.4194),
    GeoPoint(latitude: 37.7759, longitude: -122.4184),
    GeoPoint(latitude: 37.7769, longitude: -122.4204),
  ],
));

Project Tooling #

Locus includes a CLI to help with configuration and diagnostics:

# Automate native permission setup
dart run locus:setup

# Run environment diagnostics
dart run locus:doctor

Architecture #

Locus uses a feature-first architecture:

lib/src/
├── features/
│   ├── location/      # Core location tracking
│   ├── geofencing/    # Circular & polygon geofences
│   ├── battery/       # Battery optimization
│   ├── privacy/       # Privacy zones
│   ├── trips/         # Trip detection
│   ├── sync/          # HTTP sync
│   ├── tracking/      # Tracking profiles
│   └── diagnostics/   # Debug tools
├── shared/            # Common models
├── core/              # Infrastructure
└── config/            # Configuration

License #

Locus is licensed under the PolyForm Small Business License 1.0.0.

• Free for individuals and small businesses (< $250k annual revenue).
• Professional/Enterprise licenses available for larger organizations.

See LICENSE and LICENSING.md for full terms.