Titanium SDK

# Titanium.Geolocation

The top level Geolocation module. The Geolocation module is used for accessing device location based information.

Availability
0.8
0.8
9.2.0
Extends
Titanium.Module

# Overview

This module combines two sets of features:

  • Location services. Determining the location of the device.

  • Geocoding and reverse geocoding. Converting geographic coordinates into addresses, and converting addresses into geographic coordinates.

Using location services can have a significant impact on a device's battery life, so it's important to use them in the most efficient manner possible. Power consumption is strongly influenced by the accuracy and frequency of location updates required by your application.

The location services systems of the underlying platforms are very different, so there are significant implementation differences between the platforms.

The basic methods of requesting location information and receiving location updates are essentially the same on all platforms. However, the method of configuring the accuracy and frequency of location updates is different for each platform.

# Getting Location Information

There are two ways to get location information:

NOTE: Location services stay enabled for as long as a listener is registered for the location event, so be sure to remove the event listener when you do not require location updates.

# Configurating Location Updates on iOS

In iOS, the accuracy (and power consumption) of location services is primarily determined by the Titanium.Geolocation.accuracy setting. This can be set to one of the following values:

Based on the accuracy you choose, iOS uses its own logic to select location providers and filter location updates to provide location updates that meet your accuracy requirements.

You can further limit power consumption on iOS by setting the Titanium.Geolocation.distanceFilter property to eliminate position updates when the user is not moving.

In order to receive the user's location, add either the NSLocationWhenInUseUsageDescription (opens new window) or NSLocationAlwaysUsageDescription (opens new window) key to the iOS plist section of the project's tiapp.xml file.

<ti:app>
    <ios>
        <plist>
            <dict>
                <key>NSLocationAlwaysUsageDescription</key>
                <string>
                    Specify the reason for accessing the user's location information.
                    This appears in the alert dialog when asking the user for permission to
                    access their location.
                </string>
            </dict>
        </plist>
    </ios>
</ti:app>

For iOS 11 and later, also add the NSLocationAlwaysAndWhenInUseUsageDescription (opens new window) when planning to request the "Always" permission. Using the above key, you are also able to upgrade your permissions from "When in Use" to "Always", which is the recommended way for managing location permissions in iOS 11 and later. Please also remember to request your desired location-permissions before using any geolocation-related API in order to receive the best usability and permission-control during the app-lifecycle using Titanium.Geolocation.hasLocationPermissions and Titanium.Geolocation.requestLocationPermissions. Also note that you also need to include the NSLocationWhenInUseUsageDescription key in any case when targeting iOS 11 and later. Descriptive error-logs will be thrown if required permissions are missing.

# Configurating Location Updates on Android

On Android, two different location service modes are supported: simple, and manual.

As of Titanium SDK 7.1.0 and later, including the ti.playservices (opens new window) module will allow Google Play Services to be used by default to obtain location information. This means the provider passed into Titanium.Geolocation.Android.createLocationProvider will be ignored, as Google Play Services will select the best provider based on current device conditions. If Google Play Services is not available it will fallback to previous behaviour of using Android location APIs.

To retrieve location events:

var win = Ti.UI.createWindow({ backgroundColor: 'white' });

Ti.Geolocation.accuracy = Ti.Geolocation.ACCURACY_HIGH;

function getLocation() {
    Ti.Geolocation.addEventListener('location', function(e) {
        alert(JSON.stringify(e, null, 2));
    });
}

win.addEventListener('open', function() {
    if (Ti.Geolocation.hasLocationPermissions()) {
        getLocation();
      } else {
        Ti.Geolocation.requestLocationPermissions(Ti.Geolocation.AUTHORIZATION_ALWAYS, function(e) {
            if (e.success) {
                getLocation();
            } else {
                alert('could not obtain location permissions');
            }
        });
    }
});

win.open();

# Using the Compass

Both iOS and Android support a receiving heading updates from a hardware compass, if available.

Check the Titanium.Geolocation.hasCompass property to see if the current device supports a compass.

To retrieve compass readings, you can either use Titanium.Geolocation.getCurrentHeading as shown in the previous example, or add a listener for the Titanium.Geolocation.heading event, as shown below:

function compassHandler (e) {
  if (e.success) {
    Ti.API.info('Heading: ' + e.heading.magneticHeading);
  }
}
Ti.Geolocation.addEventListener('heading', compassHandler);

Note that Android did not include a success property in the heading event prior to SDK 7.5.0. Heading events are only generated on Android when heading data is available. So if success is undefined on prior SDK versions, we assume that the event contains valid compass data.

To obtain true heading data for the compass (as opposed to magnetic heading data), a current location fix is required. See the notes on HeadingData.trueHeading for more information.

As with location updates, the application should unregister for heading updates when it is no longer being used, or when it goes into the background. Use removeEventListener to stop heading updates:

Ti.Geolocation.removeEventListener('heading', compassHandler);

Finally, note that neither the Android emulator nor the iOS simulator provide compass support. Compass code must be tested on physical devices.

# Geocoding Services

The module provides two methods, Titanium.Geolocation.forwardGeocoder and Titanium.Geolocation.reverseGeocoder to convert between geographic coordinates and addresses. These methods map to MapQuest Open Nominatim Search Service.

While this API has the advantage that it has no daily usage limits, please note that the data backing this API is crowd sourced and might not return proper values for valid addresses and geographic coordinates.

If geocoding services are essential component of the application, developers are encouraged to use commercial geocoding providers.

# Properties

# accuracy

Availability
0.8
0.8
9.2.0
accuracy :Number

Specifies the requested accuracy for location updates.

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.

This API can be assigned the following constants:

# activityType

Availability
3.1.0
9.2.0
activityType :Number

The type of user activity to be associated with the location updates.

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.

This API can be assigned the following constants:

Default: Titanium.Geolocation.ACTIVITYTYPE_OTHER

# allowsBackgroundLocationUpdates

Availability
5.0.0
9.2.0
allowsBackgroundLocationUpdates :Boolean

Determines if the app can do background location updates.

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

Default: false

# apiName READONLY

Availability
3.2.0
3.2.0
9.2.0
apiName :String

The name of the API that this proxy corresponds to.

The value of this property is the fully qualified name of the API. For example, Titanium.UI.Button returns Ti.UI.Button.

# bubbleParent

Availability
3.0.0
3.0.0
9.2.0
bubbleParent :Boolean

Indicates if the proxy will bubble an event to its parent.

Some proxies (most commonly views) have a relationship to other proxies, often established by the add() method. For example, for a button added to a window, a click event on the button would bubble up to the window. Other common parents are table sections to their rows, table views to their sections, and scrollable views to their views. Set this property to false to disable the bubbling to the proxy's parent.

Default: true

# distanceFilter

Availability
0.8
9.2.0
distanceFilter :Number

The minimum change of position (in meters) before a 'location' event is fired.

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

Default: 0

# hasCompass READONLY

Availability
0.8
0.8
9.2.0
hasCompass :Boolean

Indicates whether the current device supports a compass.

# headingFilter

Availability
10.1.0
0.8
9.2.0
headingFilter :Number

Minimum heading change (in degrees) before a heading event is fired.

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

Default: 0 (No limit on heading updates)

# headingTime

Availability
10.1.0
headingTime :Number

Interval in milliseconds before a heading event is fired.

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

Default: 250

# lastGeolocation READONLY

Availability
3.1.2
3.1.2
9.2.0
lastGeolocation :String

JSON representation of the last geolocation received.

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.

# lifecycleContainer

Availability
3.6.0
lifecycleContainer :Titanium.UI.Window | Titanium.UI.TabGroup

The Window or TabGroup whose Activity lifecycle should be triggered on the proxy.

If this property is set to a Window or TabGroup, then the corresponding Activity lifecycle event callbacks will also be called on the proxy. Proxies that require the activity lifecycle will need this property set to the appropriate containing Window or TabGroup.

# locationAccuracyAuthorization READONLY

Availability
9.2.0
locationAccuracyAuthorization :Number

A value that indicates the level of location accuracy the app has permission to use.

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

This API can be assigned the following constants:

Default: Titanium.Geolocation.ACCURACY_AUTHORIZATION_REDUCED

# locationServicesAuthorization READONLY

Availability
0.8
9.2.0
locationServicesAuthorization :Number

Returns an authorization constant indicating if the application has access to location services.

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

This API can be assigned the following constants:

# locationServicesEnabled READONLY

Availability
0.8
0.8
9.2.0
locationServicesEnabled :Boolean

Indicates if the user has enabled or disabled location services for the device (not the application).

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.

# pauseLocationUpdateAutomatically

Availability
3.1.0
9.2.0
pauseLocationUpdateAutomatically :Boolean

Indicates whether the location updates may be paused.

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.

Default: false

# showBackgroundLocationIndicator

Availability
7.3.0
9.2.0
showBackgroundLocationIndicator :Boolean

Specifies that an indicator be shown when the app makes use of continuous background location updates.

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.

Default: false

# showCalibration

Availability
0.8
9.2.0
showCalibration :Boolean

Determines whether the compass calibration UI is shown if needed.

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

Default: true

# trackSignificantLocationChange

Availability
2.1.2
9.2.0
trackSignificantLocationChange :Boolean

Indicates if the location changes should be updated only when a significant change in location occurs.

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.

Default: false

# Methods

# addEventListener

Availability
0.8
0.8
9.2.0
addEventListener(name, callback) → void

Adds the specified callback as an event listener for the named event.

Parameters

Name Type Description
name String

Name of the event.

callback Callback<Titanium.Event>

Callback function to invoke when the event is fired.

Returns

Type
void

# applyProperties

Availability
3.0.0
3.0.0
9.2.0
applyProperties(props) → void

Applies the properties to the proxy.

Properties are supplied as a dictionary. Each key-value pair in the object is applied to the proxy such that myproxy[key] = value.

Parameters

Name Type Description
props Dictionary

A dictionary of properties to apply.

Returns

Type
void

# fireEvent

Availability
0.8
0.8
9.2.0
fireEvent(name[, event]) → void

Fires a synthesized event to any registered listeners.

Parameters

Name Type Description
name String

Name of the event.

event Dictionary

A dictionary of keys and values to add to the Titanium.Event object sent to the listeners.

Returns

Type
void

# forwardGeocoder

Availability
0.8
0.8
9.2.0
forwardGeocoder(address[, callback]) → Promise<ForwardGeocodeResponse>

Resolves an address to a location.

Parameters

Name Type Description
address String

address to resolve.

callback Callback<ForwardGeocodeResponse>

Function to invoke on success or failure. Optional on SDK 10, as this method will return a Promise, which may be used to handle the result.

Returns

On SDK 10+, this method will return a Promise whose resolved value is equivalent to that passed to the optional callback argument.

Type
Promise<ForwardGeocodeResponse>

# getCurrentHeading

Availability
0.8
0.8
9.2.0
getCurrentHeading([callback]) → Promise<HeadingResponse>

Retrieves the current compass heading.

Parameters

Name Type Description
callback Callback<HeadingResponse>

Function to invoke on success or failure of obtaining the current heading. Optional on SDK 10, as this method will return a Promise, which may be used to handle the result.

Returns

On SDK 10+, this method will return a Promise whose resolved value is equivalent to that passed to the optional callback argument.

Type
Promise<HeadingResponse>

# getCurrentPosition

Availability
0.8
0.8
9.2.0
getCurrentPosition([callback]) → Promise<LocationResults>

Retrieves the last known location from the device.

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".

Parameters

Name Type Description
callback Callback<LocationResults>

Function to invoke on success or failure of obtaining the current location. Optional on SDK 10, as this method will return a Promise, which may be used to handle the result.

Returns

On SDK 10+, this method will return a Promise whose resolved value is equivalent to that passed to the optional callback argument.

Type
Promise<LocationResults>

# hasLocationPermissions

Availability
5.1.0
5.1.0
9.2.0
hasLocationPermissions(authorizationType) → Boolean

Returns true if the app has location access.

Parameters

Name Type Description
authorizationType Number

Types of geolocation's authorizations. This is an iOS only parameter and is ignored on Android.

Returns

Type
Boolean

# removeEventListener

Availability
0.8
0.8
9.2.0
removeEventListener(name, callback) → void

Removes the specified callback as an event listener for the named event.

Multiple listeners can be registered for the same event, so the callback parameter is used to determine which listener to remove.

When adding a listener, you must save a reference to the callback function in order to remove the listener later:

var listener = function() { Ti.API.info("Event listener called."); }
window.addEventListener('click', listener);

To remove the listener, pass in a reference to the callback function:

window.removeEventListener('click', listener);

Parameters

Name Type Description
name String

Name of the event.

callback Callback<Titanium.Event>

Callback function to remove. Must be the same function passed to addEventListener.

Returns

Type
void

# requestLocationPermissions

Availability
5.1.0
5.1.0
9.2.0
requestLocationPermissions(authorizationType[, callback]) → Promise<LocationAuthorizationResponse>

Requests for location access.

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 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:

Parameters

Name Type Description
authorizationType Number

Types of geolocation's authorizations. This is an iOS only parameter and is ignored on Android.

callback Callback<LocationAuthorizationResponse>

Function to call upon user decision to grant location access. Optional on SDK 10, as this method will return a Promise, which may be used to handle the result.

Returns

On SDK 10+, this method will return a Promise whose resolved value is equivalent to that passed to the optional callback argument.

Type
Promise<LocationAuthorizationResponse>

# requestTemporaryFullAccuracyAuthorization

Availability
9.2.0
requestTemporaryFullAccuracyAuthorization(purposeKey, callback) → void

Requests the user's permission to temporarily use location services with full accuracy.

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>
                        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>
                        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.

Parameters

Name Type Description
purposeKey String

A key in the NSLocationTemporaryUsageDescriptionDictionary dictionary of the app's tiapp.xml file. The value for this key is an app-provided string that describes the reason for accessing location data with full accuracy.

callback Callback<LocationAccuracyAuthorizationResponse>

Function to call upon user decision to grant authorization.

Returns

Type
void

# reverseGeocoder

Availability
0.8
0.8
9.2.0
reverseGeocoder(latitude, longitude[, callback]) → Promise<ReverseGeocodeResponse>

Tries to resolve a location to an address.

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.

Parameters

Name Type Description
latitude Number

Latitude to search, specified in decimal degrees.

longitude Number

Longitude to search, specified in decimal degrees.

callback Callback<ReverseGeocodeResponse>

Function to invoke on success or failure. Optional on SDK 10, as this method will return a Promise, which may be used to handle the result.

Returns

On SDK 10+, this method will return a Promise whose resolved value is equivalent to that passed to the optional callback argument.

Type
Promise<ReverseGeocodeResponse>

# Events

# calibration

Availability
0.8
9.2.0

Fired when the device detects interface and requires calibration.

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

# heading

Availability
0.8
0.8
9.2.0

Fired when an heading update is received.

Properties

Name Type Description
code Number

If success is false, the error code is available.

success Boolean

Indicate if the heading event was successfully received. Android returns this since SDK 7.5.0.

error String

If success is false, a string describing the error.

heading HeadingData

Dictionary object containing the heading data.

source Object

Source object that fired the event.

type String

Name of the event fired.

bubbles Boolean

True if the event will try to bubble up if possible.

cancelBubble Boolean

Set to true to stop the event from bubbling.

# location

Availability
0.8
0.8
9.2.0

Fired when a location update is received.

Properties

Name Type Description
code Number

if success is false, the error code if available.

success Boolean

Indicates if location data was successfully retrieved.

provider LocationProviderDict

If success is true, object describing the location provider generating this update.

coords LocationCoordinates

If success is true, actual location data for this update.

error String

If success is false, a string describing the error.

source Object

Source object that fired the event.

type String

Name of the event fired.

bubbles Boolean

True if the event will try to bubble up if possible.

cancelBubble Boolean

Set to true to stop the event from bubbling.

# locationupdatepaused

Availability
3.1.0
9.2.0

Fired when location updates are paused by the OS.

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.

# locationupdateresumed

Availability
3.1.0
9.2.0

Fired when location manager is resumed by the OS.

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.

# authorization

Availability
3.4.0
9.2.0

Fired when changes are made to the authorization status for location services.

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.

Properties

Name Type Description
authorizationStatus Number

New authorization status for the application.

source Object

Source object that fired the event.

type String

Name of the event fired.

bubbles Boolean

True if the event will try to bubble up if possible.

cancelBubble Boolean

Set to true to stop the event from bubbling.

# Constants

# ACCURACY_AUTHORIZATION_FULL

Availability
9.2.0
ACCURACY_AUTHORIZATION_FULL :Number

The user authorized the app to access location data with full accuracy.

# ACCURACY_AUTHORIZATION_REDUCED

Availability
9.2.0
ACCURACY_AUTHORIZATION_REDUCED :Number

The user authorized the app to access location data with reduced accuracy.

# ACCURACY_BEST

Availability
0.8
9.2.0
ACCURACY_BEST :Number

Use with accuracy to request the best accuracy available.

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.

# ACCURACY_BEST_FOR_NAVIGATION

Availability
3.1.0
9.2.0
ACCURACY_BEST_FOR_NAVIGATION :Number

Use with accuracy to request highest possible accuracy and combine it with additional sensor data.

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.

# ACCURACY_HIGH

Availability
2.0.0
2.0.0
9.2.0
ACCURACY_HIGH :Number

Use with accuracy to request more accurate location updates with higher battery usage.

Using this value on Android enables simple mode operation.

# ACCURACY_HUNDRED_METERS

Availability
0.8
9.2.0
ACCURACY_HUNDRED_METERS :Number

Use with accuracy to request location updates accurate to the nearest 100 meters.

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

# ACCURACY_KILOMETER

Availability
0.8
9.2.0
ACCURACY_KILOMETER :Number

Use with accuracy to request location updates accurate to the nearest kilometer.

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

# ACCURACY_LOW

Availability
2.0.0
2.0.0
9.2.0
ACCURACY_LOW :Number

Use with accuracy to request less accurate location updates with lower battery usage.

Using this value on Android enables simple mode operation.

# ACCURACY_NEAREST_TEN_METERS

Availability
0.8
9.2.0
ACCURACY_NEAREST_TEN_METERS :Number

Use with accuracy to request location updates accurate to the nearest 10 meters.

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

# ACCURACY_REDUCED

Availability
9.2.0
ACCURACY_REDUCED :Number

The level of accuracy used when an app isn’t authorized for full accuracy location data.

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.

# ACCURACY_THREE_KILOMETERS

Availability
0.8
9.2.0
ACCURACY_THREE_KILOMETERS :Number

Use with accuracy to request location updates accurate to the nearest three kilometers.

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

# ACTIVITYTYPE_AUTOMOTIVE_NAVIGATION

Availability
3.1.0
9.2.0
ACTIVITYTYPE_AUTOMOTIVE_NAVIGATION :String

The location data is used for tracking location changes to the automobile specifically during vehicular navigation.

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.

# ACTIVITYTYPE_FITNESS

Availability
3.1.0
9.2.0
ACTIVITYTYPE_FITNESS :String

The location data is used for tracking any pedestrian-related activity.

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.

# ACTIVITYTYPE_OTHER

Availability
3.1.0
9.2.0
ACTIVITYTYPE_OTHER :String

The location data is being used for an unknown activity.

Used with activityType.

# ACTIVITYTYPE_OTHER_NAVIGATION

Availability
3.1.0
9.2.0
ACTIVITYTYPE_OTHER_NAVIGATION :String

The location data is used for tracking movements of other types of vehicular navigation that are not automobile related.

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.

# AUTHORIZATION_ALWAYS

Availability
3.4.0
9.2.0
AUTHORIZATION_ALWAYS :Number

A locationServicesAuthorization value indicating that the application is authorized to start location services at any time. This authorization includes the use of all location services, including monitoring regions and significant location changes.

# AUTHORIZATION_AUTHORIZED DEPRECATED

Availability
0.8
9.2.0
AUTHORIZATION_AUTHORIZED :Number

DEPRECATED SINCE 7.0.0

Use AUTHORIZATION_ALWAYS as advised by Apple.

A locationServicesAuthorization value indicating that the application is authorized to use location services.

# AUTHORIZATION_DENIED

Availability
0.8
9.2.0
AUTHORIZATION_DENIED :Number

A locationServicesAuthorization value indicating that the application is not authorized to use location services, or location services are disabled.

# AUTHORIZATION_RESTRICTED

Availability
0.8
9.2.0
AUTHORIZATION_RESTRICTED :Number

A locationServicesAuthorization value indicating that the application is not authorized to use location servies and the user cannot change this application's status.

# AUTHORIZATION_UNKNOWN

Availability
0.8
9.2.0
AUTHORIZATION_UNKNOWN :Number

A locationServicesAuthorization value indicating that the authorization state is unknown.

# AUTHORIZATION_WHEN_IN_USE

Availability
3.4.0
9.2.0
AUTHORIZATION_WHEN_IN_USE :Number

A locationServicesAuthorization value indicating that the application is authorized to start most location services only while running in the foreground.

# ERROR_DENIED

Availability
0.8
9.2.0
ERROR_DENIED :Number

Error code indicating that the user denied access to the location service.

# ERROR_HEADING_FAILURE

Availability
0.8
9.2.0
ERROR_HEADING_FAILURE :Number

Error code indicating that the heading could not be determined.

# ERROR_LOCATION_UNKNOWN

Availability
0.8
9.2.0
ERROR_LOCATION_UNKNOWN :Number

Error code indicating that the user's location could not be determined.

# ERROR_NETWORK

Availability
0.8
9.2.0
ERROR_NETWORK :Number

Error code indicating that the network was unavailable.

# ERROR_REGION_MONITORING_DELAYED

Availability
0.8
9.2.0
ERROR_REGION_MONITORING_DELAYED :Number

Error code indicating that region monitoring is delayed.

# ERROR_REGION_MONITORING_DENIED

Availability
0.8
9.2.0
ERROR_REGION_MONITORING_DENIED :Number

Error code indicating that region monitoring is denied.

# ERROR_REGION_MONITORING_FAILURE

Availability
0.8
9.2.0
ERROR_REGION_MONITORING_FAILURE :Number

Error code indicating a region monitoring failure.

Contents