LocationService Data Types

LocationService defines several data types.

Property NameTypeDescriptionExample
coordsCoordinatesThe physical location.{ latitude: 37.79542, longitude: -122.39357, ... }
timestampNumberThe time of the location reading, measured in milliseconds since January 1, 1970.1633040973009

An object representing a specific point located on the planet Earth. Includes velocity details, if available. Includes accuracy information, to the best of the device’s ability to evaluate. Similar to a GeolocationCoordinates in the Geolocation Web API.

Property NameTypeDescriptionExample
latitudeNumberThe latitude, in degrees. Ranges from -90 to 90.37.785834
longitudeNumberThe longitude, in degrees. Ranges from -180 to 180.-122.406417
accuracyNumberOptional. Accuracy of the location measurement, in meters, as a radius around the measurement.5
altitudeNumberOptional. Meters above sea level.0
altitudeAccuracyNumberOptional. Accuracy of the altitude measurement, in meters.-1
speedNumberOptional. Velocity of motion, if any, in meters per second.0
speedAccuracyNumberOptional. Accuracy of the speed measurement, in meters.-1
headingNumberOptional. Direction of motion, in degrees from true north. Ranges from 0 to 360.0
headingAccuracyNumberOptional. Accuracy of the heading measurement, in degrees.-1

As illustrated in the preceding examples, accuracy and other fields can be set to -1 as a special value that indicates Not Recorded. This can be due to a number of reasons, including temporary environmental conditions or permanent hardware limitations. Check for the -1 value if you depend on these fields.

Direction, as indicated by heading, is measured in degrees from due north. Positive values proceed clockwise around the compass. A compass, like a circle, has 360°, and so the values 0 and 360 are equivalent. While 360° is a valid value for heading, due north registers as 0° when returned by LocationService.

An object representing configuration details for a location service session.

Property NameTypeDescriptionExample
enableHighAccuracyBooleanWhether to use high accuracy mode when determining location. Set to true to prioritize location accuracy. Set to false to prioritize battery life and response time.false

When enableHighAccuracy is set to false, accuracy is approximately to the nearest city block, or roughly 100 meters. The impact of your component on battery use is minimal.

When enableHighAccuracy is set to true, accuracy is as high as the device’s positioning hardware can achieve and your app’s permissions allow. If you’re making many requests, the impact of your component on battery use can be significant. Use high accuracy only when your feature needs it.

An object representing an error that occurred when accessing LocationService features.

Property NameTypeDescription
codeLocationServiceFailureCodeA value representing the reason for a location error. Possible failure codes include the following:
  • locationServiceDisabled
  • userDisabledPermissions
  • userDeniedPermission
  • unavailableOnHardware
  • nativeError
messageStringA string value explaining the reason for the failure. This value is suitable for use in user interface messages. The message is provided in English, and isn’t localized.

nativeError is a special case, and represents an error that’s specific to the underlying platform, Android or iOS. If you receive this failure, check the message value for details.