Positions

_|

The sense::IPosition and sense::IImprovedPosition classes provide a comprehensive representation of geographical and movement data for GPS-based systems. They include details like coordinates, speed, altitude, direction, and accuracy, along with road-related metadata such as speed limits and modifiers. With robust support for position quality assessment and timestamped data, it is well-suited for navigation and sensor-driven applications.

tip

Do not confuse Coordinates with Position. The Coordinates class represents a geographic location using latitude, longitude, and altitude, and is used widely throughout the SDK. In contrast, sense::IPosition and sense::IImprovedPosition carry additional sensor data and are primarily used to represent the user's current location and movement.

Instantiating GemPositions

The sense::IPosition class can be instantiated using the provided methods within the sense::DataFactory class. Additionally, it can be accessed through the methods exposed by the Maps SDK for C++. For more details, refer to the Get Started with Positioning guide.

Raw position data

Raw position data represents unprocessed data from the GPS sensors of devices. It provides basic information. It corresponds to the sense::IPosition interface.

Map matched position data

Map matching is a method in location-based services that aligns raw GPS data with a digital map, correcting inaccuracies by snapping the position to the nearest logical location, such as roads. It corresponds with the sense::IImprovedPosition interface.

Raw position data vs map matched position data

The Map Matched positions provide more information, as it can be seen in the table below:

Getters	Raw	Map Matched	When is available	Description
getAcquisitionTimestamp	✅	✅	always	The system time when the data was collected from sensors.
getSatelliteTimestamp	✅	✅	always	The satellite timestamp when position was collected by the sensors.
getProvider	✅	✅	always	The provider type (GPS, network, unknown)
getLatitude & getLongitude	✅	✅	hasCoordinates	The latitude and longitude at the position in degrees
getAltitude	✅	✅	hasAltitude	The altitude at the given position. Might be negative
getSpeed	✅	✅	hasSpeed	The current speed (always non-negative)
getSpeedAccuracy	✅	✅	hasSpeedAccuracy	The current speed accuracy (always non-negative). Typical accuracy is 2 m/s in good conditions
getCourse	✅	✅	hasCourse	The current direction of movement in degrees (0 north, 90 east, 180 south, 270 west)
getCourseAccuracy	✅	✅	hasCourseAccuracy	The current heading accuracy is degrees (typical accuracy is 25 degrees)
getHorizontalAccuracy	✅	✅	hasHorizontalAccuracy	The horizontal accuracy in meters. Always positive. (typical accuracy 5-20 meters)
getVerticalAccuracy	✅	✅	hasVerticalAccuracy	The vertical accuracy in meters. Always positive.
getFixQuality	✅	✅	always	The accuracy quality (inertial – based on extrapolation, low – inaccurate, high – good accuracy, invalid – unknown)
getCoordinates	✅	✅	hasCoordinates	The coordinates of the position
getRoadModifiers	❌	✅	hasRoadLocalization	The road modifiers (such as tunnel, bridge, ramp, etc.)
getRoadSpeedLimit	❌	✅	always	The speed limit on the current road in m/s. It is 0 if no speedLimit information is available
getTerrainAltitude	❌	✅	hasTerrainData	The terrain altitude in meters. Might be negative. It can be different than altitude
getTerrainSlope	❌	✅	hasTerrainData	The current terrain slope in degrees. Positive values for ascent, negative values for descent.
getRoadAddress	❌	✅	always	The current address.

note

The getRoadSpeedLimit field may not always have a value, even if the position is map matched. This can happen if data is unavailable for the current road segment or if the position is not on a road. In such cases, the getRoadSpeedLimit field will be set to 0.

tip

One common use case for getSpeed and getRoadSpeedLimit is to check if a user is exceeding the legal speed limit. The AlarmService class offers a reliable solution for this scenario. Refer to the speed warnings guide for more details.