The top level Geolocation module. The Geolocation module is used for accessing device location based information.
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.
There are two ways to get location information:
Make a one-time request with getCurrentPosition.
Register to receive location updates by adding an event listener for the location event.
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.
In iOS, the accuracy (and power consumption) of location services is primarily determined by the 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 distanceFilter property to eliminate position updates when the user is not moving.
For iOS 8 and later, add either the
NSLocationWhenInUseUsageDescription
or
NSLocationAlwaysUsageDescription
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
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 hasLocationPermissions
and NSLocationWhenInUseUsageDescription key
in any case when targeting iOS 11 and later. Descriptive error-logs will be thrown if required permissions are missing.
Prior to Titanium Mobile 2.0, Titanium attempted to follow the iOS model on Android, but this didn't fit the native Android model well. In Release 2.0, three different location service modes are supported on Android: simple, manual, and legacy.
Simple mode provides a compromise mode that provides adaquate support for undemanding location applications without requiring developers to write a lot of Android-specific code. To use simple mode:
Leave the Titanium.Geolocation.Android.manualMode flag set to false (the
default value).
Set the accuracy property to either ACCURACY_HIGH or ACCURACY_LOW.
Manual mode gives developers low-level control of location updates, including enabling individual location providers and filtering updates, for the best combination of accuracy and battery life.
Manual mode is used when the Titanium.Geolocation.Android.manualMode flag is set
to true. In manual mode, the accuracy property is not used, and all
configuration is done through the Titanium.Geolocation.Android module.
Legacy mode is the mode that existed prior to 2.0. Legacy mode is
used when the manualMode flag is false and the accuracy property is
set to one of the iOS ACCURACY constants:
This mode is deprecated and should not be used for new development.
In this mode, the specified accuracy value determines the
minimum distance between location updates. If accuracy is set to
ACCURACY_BEST, no distance filter is used on updates.
In legacy mode, only a single location provider (GPS, network, or passive) is enabled at a time. You can specify a the location provider using the preferredProvider property.
You can also specifying a desired update frequency using the
frequency property. The preferredProvider
and frequency properties are not used in any other mode.
As of Titanium SDK 7.1.0 and later, including ti.playservices will allow Google Play Services to be used by
default to obtain location information. This means the provider passed into 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: 'gray' });
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();
Both iOS and Android support a receiving heading updates from a hardware compass, if available.
Check the hasCompass property to see if the current device supports a compass.
To retrieve compass readings, you can either use getCurrentHeading as shown in the previous example, or add a listener for the heading event, as shown below:
var compassHandler = function(e) {
if (e.success === undefined || e.success) {
Ti.API.info("Heading: " + e.heading.magneticHeading);
}
}
Ti.Geolocation.addEventListener("heading", compassHandler);
Note that Android does not include a success property in the heading event.
Heading events are only generated on Android when heading data is available. So if
success is undefined, 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 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.
The module provides two methods, forwardGeocoder and 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.
Use with accuracy to request the best accuracy available.
deprecated
[object Object]
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.
Use with accuracy to request highest possible accuracy and combine it with additional sensor data.
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.
Use with accuracy to request location updates accurate to the nearest 100 meters.
deprecated
[object Object]
Using this value on Android enables legacy mode operation, which is not recommended.
Use with accuracy to request location updates accurate to the nearest kilometer.
deprecated
[object Object]
Using this value on Android enables legacy mode operation, which is not recommended.
Use with accuracy to request location updates accurate to the nearest 10 meters.
deprecated
[object Object]
Using this value on Android enables legacy mode operation, which is not recommended.
Use with accuracy to request location updates accurate to the nearest three kilometers.
deprecated
[object Object]
Using this value on Android enables legacy mode operation, which is not recommended.
The location data is used for tracking location changes to the automobile specifically during vehicular navigation.
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. Available in iOS 6.0 and later.
The location data is used for tracking any pedestrian-related activity.
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.Available in iOS 6.0 and later.
The location data is being used for an unknown activity.
The location data is being used for an unknown activity.
Used with activityType. Available in iOS 6.0 and later.
The location data is used for tracking movements of other types of vehicular navigation that are not automobile related.
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. Available in iOS 6.0 and later.
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.
Requires: iOS 8.0 and later
A locationServicesAuthorization value indicating that the application is authorized to use location services.
deprecated since 7.0.0
Use <Titanium.Geolocation.AUTHORIZATION_ALWAYS> as advised by Apple.
A locationServicesAuthorization value indicating that the application is not authorized to use location services, or location services are disabled.
A locationServicesAuthorization value indicating that the application is not authorized to use location servies and the user cannot change this application's status.
A locationServicesAuthorization value indicating that the authorization state is unknown.
A locationServicesAuthorization value indicating that the authorization state is unknown.
This value is always returned if the device is running an iOS release prior to 4.2.
A locationServicesAuthorization value indicating that the application is authorized to start most location services only while running in the foreground.
Requires: iOS 8.0 and later
Error code indicating that the user denied access to the location service.
Error code indicating that the user denied access to the location service.
Error code indicating that the heading could not be determined.
Error code indicating that the heading could not be determined.
Error code indicating that the user's location could not be determined.
Error code indicating that the user's location could not be determined.
Error code indicating that the network was unavailable.
Error code indicating that the network was unavailable.
Error code indicating that region monitoring is delayed.
Requires: iOS 4.0 and later
Error code indicating that region monitoring is denied.
Requires: iOS 4.0 and later
Error code indicating a region monitoring failure.
Requires: iOS 4.0 and later
Specifies the GPS location provider.
Specifies the GPS location provider.
Used with preferredProvider, LocationProvider.name, LocationRule.provider.
In general, the GPS provider has the highest power consumption and the highest accuracy, but this may vary. In some circumstances, the network provider may be more reliable.
Specifies the network location provider.
Specifies the network location provider.
Used with preferredProvider, LocationProvider.name, LocationRule.provider.
Generally requires less power than the GPS provider and provides less accurate results, but may produce very accurate results in densely-populated areas with many cell towers and WiFi networks.
Specifies the passive location provider.
Specifies the passive location provider.
Used with preferredProvider, LocationProvider.name, LocationRule.provider.
This provider only uses cached location information, so it does not use any power, but makes no guarantee that the location results are recent.
Specifies the requested accuracy for location updates.
Specifies the requested accuracy for location updates.
For basic location updates on all platforms, set accuracy to either:
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.
Note that for backwards compatibility, Android supports using the iOS accuracy constants.
This usage is deprecated. Applications using one of the iOS constants should
migrate to using ACCURACY_HIGH, ACCURACY_LOW, or Android manual mode.
This API can be assigned the following constants:
The type of user activity to be associated with the location updates. Available in iOS 6.0 and later.
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: ACTIVITYTYPE_OTHER
Determines if the app can do background location updates.
Requires: iOS 9.0 and later
When UIBackgroundModes include location in tiapp.xml, this property is
set to true by default. Available in iOS 9.0 and later.
Default: true
The name of the API that this proxy corresponds to.
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, Button
returns Ti.UI.Button.
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
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
Requested frequency for location updates, in milliseconds.
deprecated
2.0.0 Android legacy mode operation is deprecated. For new development, use either simple mode or manual mode. See "Configurating Location Updates on Android" in the main description of this class for more information.
Setting a frequency value enables legacy location mode on Android. Note that only a single provider can be active at one time in legacy mode.
Note that the frequency value is used as a guideline: there are no guarantees that the device will provide updates at the specified frequency.
A lower frequency value generally increases power consumption. A value of 0 means that updates should be generated as quickly as possible.
Indicates whether the current device supports a compass.
Indicates whether the current device supports a compass.
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)
JSON representation of the last geolocation received.
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.
The Window or TabGroup whose Activity lifecycle should be triggered on the proxy.
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.
Returns an authorization constant indicating if the application has access to location services.
Requires: iOS 4.2 and later
Always returns AUTHORIZATION_UNKNOWN on pre-4.2 devices.
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:
Indicates if the user has enabled or disabled location services for the device (not the application).
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 OS 2.2 and above, there is a new, "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.
Indicates whether the location updates may be paused. Available in iOS 6.0 and later.
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
Determines the preferred location provider.
deprecated
2.0.0 Android legacy mode operation is deprecated. For new development, use either simple mode or manual mode. See "Configurating Location Updates on Android" in the main description of this class for more information.
Setting a preferred provider enables legacy location mode on Android. Note that only a single provider can be active at one time in legacy mode.
The preferred provider affects power consumption. In general, PROVIDER_GPS
requires the most power, and PROVIDER_PASSIVE requires the least.
If undefined, the preferred provider is auto-detected.
This API can be assigned the following constants:
Default: PROVIDER_NETWORK
Text to display in the permission dialog when requesting location services.
Requires: iOS 5.0 and earlier
This property informs the end user why location services are being requested by
the application. This property is required starting in iOS 4.0.
deprecated for >= iOS6, include the NSLocationUsageDescription key with your
description in tiapp.xml instead.
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
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 is available only in iOS 4.0 and later. 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
Adds the specified callback as an event listener for the named event.
Name of the event.
Callback function to invoke when the event is fired.
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.
A dictionary of properties to apply.
Fires a synthesized event to any registered listeners.
Name of the event.
A dictionary of keys and values to add to the Titanium.Event object sent to the listeners.
Resolves an address to a location.
address to resolve.
Function to invoke on success or failure.
Retrieves the current compass heading.
Function to invoke on success or failure of obtaining the current heading.
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".
Function to invoke on success or failure of obtaining the current location.
Gets the value of the frequency property.
deprecated
2.0.0 Android legacy mode operation is deprecated. For new development, use either simple mode or manual mode. See "Configurating Location Updates on Android" in the main description of this class for more information.
Gets the value of the preferredProvider property.
deprecated
2.0.0 Android legacy mode operation is deprecated. For new development, use either simple mode or manual mode. See "Configurating Location Updates on Android" in the main description of this class for more information.
Returns true if the app has location access.
Types of geolocation's authorizations. This is an iOS 8 and above only parameter and is ignored on Android and iOS 7.
This API can be assigned the following constants:
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);
Name of the event.
Callback function to remove. Must be the same function passed to addEventListener.
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 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
Types of geolocation's authorizations. This is an iOS only parameter and is ignored on Android.
This API can be assigned the following constants:
Function to call upon user decision to grant location access.
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.
Latitude to search, specified in decimal degrees.
Longitude to search, specified in decimal degrees.
Function to invoke on success or failure.
Sets the value of the accuracy property.
New value for the property.
Sets the value of the activityType property.
New value for the property.
Sets the value of the allowsBackgroundLocationUpdates property.
New value for the property.
Sets the value of the bubbleParent property.
New value for the property.
Sets the value of the distanceFilter property.
New value for the property.
Sets the value of the frequency property.
deprecated
2.0.0 Android legacy mode operation is deprecated. For new development, use either simple mode or manual mode. See "Configurating Location Updates on Android" in the main description of this class for more information.
New value for the property.
Sets the value of the headingFilter property.
New value for the property.
Sets the value of the lifecycleContainer property.
New value for the property.
Sets the value of the locationServicesAuthorization property.
New value for the property.
Sets the value of the pauseLocationUpdateAutomatically property.
New value for the property.
Sets the value of the preferredProvider property.
deprecated
2.0.0 Android legacy mode operation is deprecated. For new development, use either simple mode or manual mode. See "Configurating Location Updates on Android" in the main description of this class for more information.
New value for the property.
Sets the value of the purpose property.
New value for the property.
Sets the value of the showCalibration property.
New value for the property.
Sets the value of the trackSignificantLocationChange property.
New value for the property.
Fired when the device detects interface and requires calibration.
When this event is fired, the OS calibration UI is being displayed to the end user.
Source object that fired the event.
Name of the event fired.
True if the event will try to bubble up if possible.
Set to true to stop the event from bubbling.
Fired when an heading update is received.
If success is false, the error code if available.
Indicate if the heading event was successfully received.
If success is false, a string describing the error.
Dictionary object containing the heading data.
Source object that fired the event.
Name of the event fired.
True if the event will try to bubble up if possible.
Set to true to stop the event from bubbling.
Fired when a location update is received.
if success is false, the error code if available.
Indicates if location data was successfully retrieved.
If success is true, object describing the location provider generating this update.
If success is true, actual location data for this update.
If success is false, a string describing the error.
Source object that fired the event.
Name of the event fired.
True if the event will try to bubble up if possible.
Set to true to stop the event from bubbling.
Fired when location updates are paused by the OS. Available in iOS 6.0 and later.
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.
Source object that fired the event.
Name of the event fired.
True if the event will try to bubble up if possible.
Set to true to stop the event from bubbling.
Fired when location manager is resumed by the OS. Available in iOS 6.0 and later.
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.
Source object that fired the event.
Name of the event fired.
True if the event will try to bubble up if possible.
Set to true to stop the event from bubbling.