Titanium.Geolocation

For basic location updates on all platforms, set accuracy to either:

• ACCURACY_HIGH for higher-quality location updates, with the higher power consumption.
• ACCURACY_LOW for lower-quality location updates with lower power consumption.

For finer-grained control on iOS, specify one of ACCURACY_BEST, ACCURACY_NEAREST_TEN_METERS, ACCURACY_HUNDRED_METERS, ACCURACY_KILOMETER, or ACCURACY_THREE_KILOMETERS.

For finer-grained control on Android, use manual mode, instead of specifing an accuracy. This mode requires more active management on the part of the application, but it is recommended to maximize accuracy and battery life. See Titanium.Geolocation.Android for details on using manual mode.

Using this value results in the most accurate location updates, and the highest battery usage.

Using this value on Android enables legacy mode operation, which is not recommended.

Using this value is intended for use in navigation applications that require precise position information at all times and are intended to be used only while the device is plugged in.

Using this value on Android enables simple mode operation.

Using this value on Android enables legacy mode operation, which is not recommended.

Using this value on Android enables legacy mode operation, which is not recommended.

Using this value on Android enables simple mode operation.

Using this value on Android enables legacy mode operation, which is not recommended.

Use with accuracy. The accuracy of location data is reduced in both space and time using approaches like selecting a nearby point of interest and updating the location at most a few times per hour. The approximate location preserves the user’s country, typically preserves the city, and is usually within 1–20 kilometers of the actual location. If your app is authorized to access location information with full accuracy, you can use this constant to access location data as if the app didn’t have that authorization.

Using this value on Android enables legacy mode operation, which is not recommended.

The information in this property is used as a cue to determine when location updates may be automatically paused. Pausing updates gives the system the opportunity to save power in situations where the user's location is not likely to be changing. For example, if the activity type is ACTIVITYTYPE_AUTOMOTIVE_NAVIGATION and no location changes have occurred recently, the radios might be powered down until movement is detected again.

Used with activityType. This activity might cause location updates to be paused only when the vehicle does not move for an extended period of time.

Used with activityType. This activity might cause location updates to be paused only when the user does not move a significant distance over a period of time.

Used with activityType.

Used with activityType. You would use this to track navigation by boat, train, or plane. Do not use this type for pedestrian navigation tracking. This activity might cause location updates to be paused only when the vehicle does not move a significant distance over a period of time.

When UIBackgroundModes include location in tiapp.xml, this property is set to true by default.

If set to 0, distance filtering is disabled, meaning that location events are generated continuously.

Set to a value greater than zero to reduce the number of heading events generated.

Set to a value greater than zero to reduce the number of heading events generated. If you target Android 12 and want to use a time below 200ms you need to add the HIGH_SAMPLING_RATE_SENSORS permission. See Motion sensors are rate-limited

LastEvent is the JSON version of the last geolocation sent by the OS. This does not trigger a geolocation attempt, nor wait for such. If no geolocation has happened, this value may be null or undefined.

If the value of this property is Titanium.Geolocation.ACCURACY_AUTHORIZATION_FULL, you can set any constant to accuracy. If value is Titanium.Geolocation.ACCURACY_AUTHORIZATION_REDUCED setting accuracy to a value other than Titanium.Geolocation.ACCURACY_REDUCED has no effect on the location information.

If locationServicesAuthorization is AUTHORIZATION_RESTRICTED, you should not attempt to re-authorize: this will lead to issues.

This method returns true if any location provider is enabled.

On Android, there is a "passive" location provider that is enabled at all times, even when the user disables both the GPS and Network location providers. Therefore, this method returns true on these devices if only there is GPS or network provider available.

Allowing the location updates to be paused can improve battery life on the target device without sacrificing location data. When this property is set to YES, the location updates are paused (and powers down the appropriate hardware) at times when the location data is unlikely to change. For example, if the user stops for food while using a navigation app, the location manager might pause updates for a period of time. You can help the determination of when to pause location updates by assigning a value to the activityType property.

Starting continuous background location updates requires the app to set UIBackgroundModes to include "location" and to set this property to true before calling getCurrentPosition with the intent to continue in the background.

Note that this property only applies to apps with Always authorization. For apps with WhenInUse authorization, the indicator is always shown when using continuous background location updates in order to maintain user visibility and that the app is still in use.

Set to false to disable display of the compass calibration UI. This may result in invalid heading data.

The trackSignificantLocationChange service offers a low-power location service for devices with cellular radios.

This service offers a significant power savings and provides accuracy that is good enough for most applications. It uses the device's cellular radio to determine the user's location and report changes in that location, allowing the system to manage power usage much more aggressively than it could otherwise. This service is also capable of waking up an application that is currently suspended or not running in order to deliver new location data.

On Android, the radios are not turned on to update the location, and a cached location is used.

On iOS the radios may be used if the location is too "old".

On Android, the request view will show if the permission is not accepted by the user, and the user did not check the box "Never ask again" when denying the request. If the user checks the box "Never ask again," the user has to manually enable the permission in device settings. If the user asks for permissions or tries to get unauthorized location information, then the app should call the request method to show the permission settings. This method requests Manifest.permission.ACCESS_FINE_LOCATION on Android. If you require other permissions, you can also use Titanium.Android.requestPermissions.

In iOS 8, Apple introduced the Info.plist keys NSLocationWhenInUseUsageDescription and NSLocationAlwaysUsageDescription that are used to display an own description while requesting location permissions. In addition to this method, you need to include one of these keys (based on how your location updates should behave) or the application will crash if your app does not.

In iOS 11, Apple introduced another Info.plist key NSLocationAlwaysAndWhenInUseUsageDescription that allows developers to upgrade their permissions from "When in Use" to "Always". In order to get the best usability for iOS 11 and later, request "When in Use" first and upgrade your location-permissions by requesting "Always" permissions later if required. If this permission-flow is not used, iOS will still ask the user to select between "When in Use", "Always", and "Don't Allow" (primary action) on iOS 11 when asking for "Always" permissions, which can lead to a higher frequence of denied permissions, so be careful requesting location permissions. The iOS 11 related upgrade-flow is available in Titanium SDK 6.3.0 and later.

Finally, iOS 11 and later will require you to always include the NSLocationWhenInUseUsageDescription permission and Titanium will throw a descriptive error-log if any required keys are missing.

More infos:

• Available Info.plist keys
• Request Always Authorization

If your app doesn't have permission to access accurate location (see locationAccuracyAuthorization, you can use this method to request temporary access to accurate location. This access will expire automatically, but it won't expire while the user is still engaged with your app. So, for example, while your app is in the foreground your app will retain the temporary access it was granted. Similarly, if your app starts a Continuous Background Location session with the background location indicator enabled (see showBackgroundLocationIndicator, your access to accurate location will remain as long as the background location indicator remains enabled. This allows your app to provide session-oriented experiences which require accurate location (e.g. fitness or navigation), even if the user has decided not to grant your app persistent access to accurate location.

You need to add key NSLocationTemporaryUsageDescriptionDictionary in tiapp.xml. See following example -

<ti:app>
    <ios>
        <plist>
            <dict>
                <key>NSLocationTemporaryUsageDescriptionDictionary</key>
                <dict>
                    <key>PurposeKey1</key>
                    [string](api:Global.String)
                        Specify the reason for accessing the user's location data with full accuracy.
                        This appears in the alert dialog when asking the user for permission to
                        access their location.
                    </string>
                    <key>PurposeKey2</key>
                    [string](api:Global.String)
                        Specify the reason for accessing the user's location data with full accuracy.
                        This appears in the alert dialog when asking the user for permission to
                        access their location.
                    </string>
                </dict>
            </dict>
        </plist>
    </ios>
</ti:app>

When CoreLocation prepares the prompt for display, it will look at the NSLocationTemporaryUsageDescriptionDictionary key in your tiapp.xml. The value should be a dictionary containing usage descriptions. The purposeKey you provide to this method must correspond to an entry in that dictionary.

The callback receives a ReverseGeocodeResponse object. If the request is successful, the object includes one or more addresses that are possible matches for the requested coordinates.

This event is fired whenever the application's ability to use location services changes. Changes can occur because the user allowed or denied the use of location services for the app or the system as a whole.

When this event is fired, the iOS calibration UI is being displayed to the end user.

This event is fired when pauseLocationUpdateAutomatically is set to true and if the OS detects that the device's location is not changing, causing it to pause the delivery of updates in order to shut down the appropriate hardware and save power.

When location updates are paused and need to be resumed (perhaps because the user is moving again), this event is fired to let the app know that it is about to begin the delivery of those updates again.