PositionService class abstract Position

Provides access to device and custom position data and playback controls.

The PositionService exposes static helpers to obtain the current device position, register continuous position listeners, and manage the position data source (live GPS, playback logs, or custom external sources). Use listeners created with addPositionListener or addImprovedPositionListener to receive continuous updates.

Raw positions are direct GPS fixes (latitude, longitude, altitude, speed, bearing, accuracy, timestamp) with no map context. See GemPosition for details. The addPositionListener method provides these raw position updates.

Improved (map-mathed) positions are post‑processed, smoothed and snapped to the road network or known paths, may include road metadata (road id, speed limit, modifiers). See GemImprovedPosition for details. The addImprovedPositionListener method provides these improved position updates.

For one-off reads use the position and improvedPosition getters. Playback controls are available via playback when the active DataSource supports it.

Data can come from the device GPS (live) or from custom/log data sources.

VERY IMPORTANT: Make sure the application has the required location permissions before setting the live data source. See the permission_handler package for more details on requesting location permissions in Flutter. Platform specific setup is required on Android and iOS to request location permissions.

Example

final locationPermissionStatus = await Permission.locationWhenInUse.request();
if (locationPermissionStatus == PermissionStatus.granted) {
  GemError setLiveDataSourceError = PositionService.setLiveDataSource();
  if (setLiveDataSourceError == GemError.success) {
    print("Live data source set successfully");
  } else {
    print("Failed to set live data source: $setLiveDataSourceError");
  }

  PositionService.addImprovedPositionListener((GemPosition position) {
    // Handle improved position updates
  });
} else {
  print("Location permission denied");
}

Constructors

PositionService()

Properties

hashCode → int: The hash code for this object.
no setterinherited
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited

Methods

noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
toString() → String: A string representation of this object.
inherited

Operators

operator ==(Object other) → bool: The equality operator.
inherited

Static Properties

improvedPosition → GemImprovedPosition?: Returns the most recent map-matched (improved) position, or null.
no setter
playback → Playback?: Returns a Playback controller when the active data source supports it.
no setter
position → GemPosition?: Returns the most recent raw position sample, or null if unavailable.
no setter
sourceType → DataSourceType: Returns the type of the current position data source.
no setter

Static Methods

addImprovedPositionListener(void positionUpdatedCallback(GemImprovedPosition position)) → GemPositionListener: Registers a callback to receive improved position updates from the active data source.
addPositionListener(void positionUpdatedCallback(GemPosition position)) → GemPositionListener: Registers a callback to receive raw position updates from the active data source.
getDataSource() → DataSource?: Returns the currently configured DataSource, or null if none is set.
removeDataSource() → void: Removes the active position data source and stops delivering new samples.
removeListener(GemPositionListener listener) → void: Unregisters a previously registered position listener.
requestLocationPermission() → Future<bool>: Requests location permission from the platform (web-only helper).
setExternalDataSource(DataSource dataSource) → GemError: Configures a custom external data source for providing position samples.
setLiveDataSource() → GemError: Sets the PositionService to use the device's live GPS data source.