Positions

_|

The GemPosition and GemImprovedPosition classes provide a representation of geographical and movement data for web-based location systems. They include details like coordinates, speed, altitude, direction, and accuracy derived from the browser's Geolocation API, along with road-related metadata such as speed limits and modifiers. With support for position quality assessment and timestamped data, they are well-suited for navigation applications.

tip

Do not confuse the Coordinates and Position classes. The Coordinates class represents geographic locations using latitude, longitude and altitude, and is widely used throughout the Maps SDK for TypeScript. In contrast, the GemPosition and GemImprovedPosition classes contain additional data from the browser's Geolocation API, and are primarily used to represent the user's location and movement details.

Browser Geolocation API

The Maps SDK for TypeScript relies on the browser's Geolocation API to obtain position data. The available position properties are limited to what the browser provides through the GeolocationCoordinates interface:

• latitude - Geographic latitude in decimal degrees
• longitude - Geographic longitude in decimal degrees
• accuracy - Horizontal accuracy in meters (always available)
• altitude - Height in meters (may be null if unavailable)
• altitudeAccuracy - Vertical accuracy in meters (may be null)
• heading - Direction of travel in degrees from north (may be null)
• speed - Current speed in meters per second (may be null)

note

Unlike native mobile SDKs, the TypeScript SDK does not have access to raw device sensors. All position data comes from the browser's Geolocation API, which varies in accuracy and available fields depending on the device, browser, and user permissions.

Instantiating GemPositions

The GemPosition class can be instantiated using the provided methods within the SenseDataFactory class. Additionally, it can be accessed through the methods exposed by the Maps SDK for TypeScript. For more details, refer to the Get Started with Positioning guide.

Raw position data

Raw position data represents unprocessed data from the browser's Geolocation API. It provides basic information and corresponds to the GemPosition 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 GemImprovedPosition interface.

Raw position data vs map matched position data

The Map Matched positions provide more information, as can be seen in the table below. Note that not all fields are guaranteed to be available from the browser's Geolocation API - availability depends on the device, browser, and GPS capabilities.

Attribute	Raw	Map Matched	Browser Support	Description
acquisitionTime	✅	✅	always	The system time when the data was collected from the browser.
satelliteTime	✅	✅	always	The timestamp when position was collected (from browser).
provider	✅	✅	always	The provider type (GPS, network, unknown)
latitude & longitude	✅	✅	always	The latitude and longitude at the position in degrees (always provided by browser)
altitude	✅	✅	optional	The altitude at the given position. Might be negative. May be null if unavailable
speed	✅	✅	optional	The current speed (always non-negative). May be null if unavailable
speedAccuracy	❌	❌	not available	Not available in browser Geolocation API
course	✅	✅	optional	The current direction of movement in degrees (0 north, 90 east, 180 south, 270 west). May be null if unavailable
courseAccuracy	❌	❌	not available	Not available in browser Geolocation API
accuracyH	✅	✅	always	The horizontal accuracy in meters. Always positive (typical accuracy 5-50 meters on web)
accuracyV	✅	✅	optional	The vertical accuracy in meters. Always positive. May be null if unavailable
fixQuality	✅	✅	always	The accuracy quality (inertial – based on extrapolation, low – inaccurate, high – good accuracy, invalid – unknown)
coordinates	✅	✅	always	The coordinates of the position
roadModifiers	❌	✅	hasRoadLocalization	The road modifiers (such as tunnel, bridge, ramp, etc.)
speedLimit	❌	✅	always	The speed limit on the current road in m/s. It is 0 if no speedLimit information is available
terrainAltitude	❌	✅	hasTerrainData	The terrain altitude in meters. Might be negative. It can be different than altitude
terrainSlope	❌	✅	hasTerrainData	The current terrain slope in degrees. Positive values for ascent, negative values for descent.
address	❌	✅	always	The current address.

note

The browser's Geolocation API does not provide speedAccuracy or courseAccuracy fields. These values are not available in the TypeScript SDK. Additionally, fields like altitude, altitudeAccuracy, heading, and speed may be null depending on the device and browser capabilities.

note

The speedLimit 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 speedLimit field will be set to 0.

tip

One common use case for speed and speedLimit is to check if a user is exceeding the legal speed limit. The AlarmService class offers a reliable solution for this scenario.