# Titanium.Geolocation
> The top level Geolocation module. The Geolocation module is used for accessing device location based information.
- Source: https://titaniumsdk.com/docs/sdk/13.1.0/Titanium.Geolocation
- Titanium SDK version: 13.1.0
- Kind: module
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK 0.1
- Extends: Titanium.Module
- Inheritance: Titanium.Module > Titanium.Proxy
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:
* Make a one-time request with [getCurrentPosition](https://titaniumsdk.com/docs/sdk/Titanium.Geolocation.md#getCurrentPosition).
* Register to receive location updates by adding an event listener for the
[location](https://titaniumsdk.com/docs/sdk/Titanium.Geolocation.md#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.
#### Configurating Location Updates on iOS
In iOS, the accuracy (and power consumption) of location services is primarily
determined by the [accuracy](https://titaniumsdk.com/docs/sdk/Titanium.Geolocation.md#accuracy) setting. This can be set
to one of the following values:
* [ACCURACY_BEST](https://titaniumsdk.com/docs/sdk/Titanium.Geolocation.md#ACCURACY_BEST) (highest accuracy and power consumption)
* [ACCURACY_BEST_FOR_NAVIGATION](https://titaniumsdk.com/docs/sdk/Titanium.Geolocation.md#ACCURACY_BEST_FOR_NAVIGATION)
* [ACCURACY_HIGH](https://titaniumsdk.com/docs/sdk/Titanium.Geolocation.md#ACCURACY_HIGH)
* [ACCURACY_NEAREST_TEN_METERS](https://titaniumsdk.com/docs/sdk/Titanium.Geolocation.md#ACCURACY_NEAREST_TEN_METERS)
* [ACCURACY_HUNDRED_METERS](https://titaniumsdk.com/docs/sdk/Titanium.Geolocation.md#ACCURACY_HUNDRED_METERS)
* [ACCURACY_KILOMETER](https://titaniumsdk.com/docs/sdk/Titanium.Geolocation.md#ACCURACY_KILOMETER)
* [ACCURACY_LOW](https://titaniumsdk.com/docs/sdk/Titanium.Geolocation.md#ACCURACY_LOW)
* [ACCURACY_THREE_KILOMETERS](https://titaniumsdk.com/docs/sdk/Titanium.Geolocation.md#ACCURACY_THREE_KILOMETERS) (lowest
accuracy and power consumption).
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](https://titaniumsdk.com/docs/sdk/Titanium.Geolocation.md#distanceFilter) property to eliminate position
updates when the user is not moving.
In order to receive the user's location, add either the
[`NSLocationWhenInUseUsageDescription`](https://developer.apple.com/library/content/documentation/General/Reference/InfoPlistKeyReference/Articles/CocoaKeys.html#//apple_ref/doc/uid/TP40009251-SW26)
or
[`NSLocationAlwaysUsageDescription`](https://developer.apple.com/library/content/documentation/General/Reference/InfoPlistKeyReference/Articles/CocoaKeys.html#//apple_ref/doc/uid/TP40009251-SW26)
key to the iOS plist section of the project's `tiapp.xml` file.
``` xml
NSLocationAlwaysUsageDescription
[string](https://titaniumsdk.com/docs/sdk/Global.String.md)
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.
```
For iOS 11 and later, also add the [`NSLocationAlwaysAndWhenInUseUsageDescription`](https://developer.apple.com/documentation/corelocation/choosing_the_authorization_level_for_location_services/request_always_authorization)
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](https://titaniumsdk.com/docs/sdk/Titanium.Geolocation.md#hasLocationPermissions)
and [Titanium.Geolocation.requestLocationPermissions](https://titaniumsdk.com/docs/sdk/Titanium.Geolocation.md#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*.
* *Simple mode* provides a compromise mode that provides adequate support for
undemanding location applications without requiring developers to
write a lot of Android-specific code. To use simple mode:
1. Leave the [Titanium.Geolocation.Android.manualMode](https://titaniumsdk.com/docs/sdk/Titanium.Geolocation.Android.md#manualMode) flag set to `false` (the
default value).
2. Set the [accuracy](https://titaniumsdk.com/docs/sdk/Titanium.Geolocation.md#accuracy) property to
either [ACCURACY_HIGH](https://titaniumsdk.com/docs/sdk/Titanium.Geolocation.md#ACCURACY_HIGH) or
[ACCURACY_LOW](https://titaniumsdk.com/docs/sdk/Titanium.Geolocation.md#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](https://titaniumsdk.com/docs/sdk/Titanium.Geolocation.Android.md#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](https://titaniumsdk.com/docs/sdk/Titanium.Geolocation.Android.md) module.
As of Titanium SDK 7.1.0 and later, including the [`ti.playservices`](https://github.com/appcelerator-modules/ti.playservices) module will allow Google Play Services
to be used by default to obtain location information. This means the provider passed into [createLocationProvider](https://titaniumsdk.com/docs/sdk/Titanium.Geolocation.Android.md#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:
``` js
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 [hasCompass](https://titaniumsdk.com/docs/sdk/Titanium.Geolocation.md#hasCompass) property to see if the current
device supports a compass.
To retrieve compass readings, you can either use
[getCurrentHeading](https://titaniumsdk.com/docs/sdk/Titanium.Geolocation.md#getCurrentHeading) as shown in the
previous example, or add a listener for the
[heading](https://titaniumsdk.com/docs/sdk/Titanium.Geolocation.md#heading) event, as shown below:
``` js
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
[trueHeading](https://titaniumsdk.com/docs/sdk/HeadingData.md#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:
``` js
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, [forwardGeocoder](https://titaniumsdk.com/docs/sdk/Titanium.Geolocation.md#forwardGeocoder) and [reverseGeocoder](https://titaniumsdk.com/docs/sdk/Titanium.Geolocation.md#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
- Type: Number
- Platforms: Android, iPhone, iPad, macOS
Specifies the requested accuracy for location updates.
For basic location updates on all platforms, set `accuracy` to either:
* [ACCURACY_HIGH](https://titaniumsdk.com/docs/sdk/Titanium.Geolocation.md#ACCURACY_HIGH) for higher-quality location
updates, with the higher power consumption.
* [ACCURACY_LOW](https://titaniumsdk.com/docs/sdk/Titanium.Geolocation.md#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 specifying 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](https://titaniumsdk.com/docs/sdk/Titanium.Geolocation.Android.md) for details on using manual mode.
Accepts: `Titanium.Geolocation.ACCURACY_BEST`, `Titanium.Geolocation.ACCURACY_BEST_FOR_NAVIGATION`, `Titanium.Geolocation.ACCURACY_HIGH`, `Titanium.Geolocation.ACCURACY_HUNDRED_METERS`, `Titanium.Geolocation.ACCURACY_KILOMETER`, `Titanium.Geolocation.ACCURACY_LOW`, `Titanium.Geolocation.ACCURACY_NEAREST_TEN_METERS`, `Titanium.Geolocation.ACCURACY_REDUCED`, `Titanium.Geolocation.ACCURACY_THREE_KILOMETERS`
### ACCURACY_AUTHORIZATION_FULL
- Type: Number
- Platforms: iPhone, iPad
- Since: Titanium SDK 9.2.0
- Requires: iOS 14.0+
- Permission: read-only
The user authorized the app to access location data with full accuracy.
### ACCURACY_AUTHORIZATION_REDUCED
- Type: Number
- Platforms: iPhone, iPad
- Since: Titanium SDK 9.2.0
- Requires: iOS 14.0+
- Permission: read-only
The user authorized the app to access location data with reduced accuracy.
### ACCURACY_BEST
- Type: Number
- Platforms: iPhone, iPad, macOS
- Permission: read-only
Use with [accuracy](https://titaniumsdk.com/docs/sdk/Titanium.Geolocation.md#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
- Type: Number
- Platforms: iPhone, iPad, macOS
- Since: Titanium SDK 3.1.0
- Permission: read-only
Use with [accuracy](https://titaniumsdk.com/docs/sdk/Titanium.Geolocation.md#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
- Type: Number
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK 2.0.0
- Permission: read-only
Use with [accuracy](https://titaniumsdk.com/docs/sdk/Titanium.Geolocation.md#accuracy) to request more
accurate location updates with higher battery usage.
Using this value on Android enables *simple mode* operation.
### ACCURACY_HUNDRED_METERS
- Type: Number
- Platforms: iPhone, iPad, macOS
- Permission: read-only
Use with [accuracy](https://titaniumsdk.com/docs/sdk/Titanium.Geolocation.md#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
- Type: Number
- Platforms: iPhone, iPad, macOS
- Permission: read-only
Use with [accuracy](https://titaniumsdk.com/docs/sdk/Titanium.Geolocation.md#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
- Type: Number
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK 2.0.0
- Permission: read-only
Use with [accuracy](https://titaniumsdk.com/docs/sdk/Titanium.Geolocation.md#accuracy) to request less
accurate location updates with lower battery usage.
Using this value on Android enables *simple mode* operation.
### ACCURACY_NEAREST_TEN_METERS
- Type: Number
- Platforms: iPhone, iPad, macOS
- Permission: read-only
Use with [accuracy](https://titaniumsdk.com/docs/sdk/Titanium.Geolocation.md#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
- Type: Number
- Platforms: iPhone, iPad
- Since: Titanium SDK 9.2.0
- Requires: iOS 14.0+
- Permission: read-only
The level of accuracy used when an app isn’t authorized for full accuracy location data.
Use with [accuracy](https://titaniumsdk.com/docs/sdk/Titanium.Geolocation.md#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
- Type: Number
- Platforms: iPhone, iPad, macOS
- Permission: read-only
Use with [accuracy](https://titaniumsdk.com/docs/sdk/Titanium.Geolocation.md#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
- Type: Number
- Platforms: iPhone, iPad, macOS
- Since: Titanium SDK 3.1.0
- Default: ``
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](https://titaniumsdk.com/docs/sdk/Titanium.Geolocation.md#ACTIVITYTYPE_AUTOMOTIVE_NAVIGATION)
and no location changes have occurred recently, the radios might be powered down
until movement is detected again.
Accepts: `Titanium.Geolocation.ACTIVITYTYPE_AUTOMOTIVE_NAVIGATION`, `Titanium.Geolocation.ACTIVITYTYPE_FITNESS`, `Titanium.Geolocation.ACTIVITYTYPE_OTHER`, `Titanium.Geolocation.ACTIVITYTYPE_OTHER_NAVIGATION`
### ACTIVITYTYPE_AUTOMOTIVE_NAVIGATION
- Type: String
- Platforms: iPhone, iPad, macOS
- Since: Titanium SDK 3.1.0
- Permission: read-only
The location data is used for tracking location changes to the automobile specifically during vehicular navigation.
Used with [activityType](https://titaniumsdk.com/docs/sdk/Titanium.Geolocation.md#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
- Type: String
- Platforms: iPhone, iPad, macOS
- Since: Titanium SDK 3.1.0
- Permission: read-only
The location data is used for tracking any pedestrian-related activity.
Used with [activityType](https://titaniumsdk.com/docs/sdk/Titanium.Geolocation.md#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
- Type: String
- Platforms: iPhone, iPad, macOS
- Since: Titanium SDK 3.1.0
- Permission: read-only
The location data is being used for an unknown activity.
Used with [activityType](https://titaniumsdk.com/docs/sdk/Titanium.Geolocation.md#activityType).
### ACTIVITYTYPE_OTHER_NAVIGATION
- Type: String
- Platforms: iPhone, iPad, macOS
- Since: Titanium SDK 3.1.0
- Permission: read-only
The location data is used for tracking movements of other types of vehicular
navigation that are not automobile related.
Used with [activityType](https://titaniumsdk.com/docs/sdk/Titanium.Geolocation.md#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.
### allowsBackgroundLocationUpdates
- Type: Boolean
- Platforms: iPhone, iPad, macOS
- Since: Titanium SDK 5.0.0
- Default: `false`
Determines if the app can do background location updates.
When `UIBackgroundModes` include `location` in tiapp.xml, this property is
set to `true` by default.
### AUTHORIZATION_ALWAYS
- Type: Number
- Platforms: iPhone, iPad, macOS
- Since: Titanium SDK 3.4.0
- Permission: read-only
A [locationServicesAuthorization](https://titaniumsdk.com/docs/sdk/Titanium.Geolocation.md#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
- Type: Number
- Platforms: iPhone, iPad, macOS
- Permission: read-only
- DEPRECATED since 7.0.0. Use [Titanium.Geolocation.AUTHORIZATION_ALWAYS](Titanium.Geolocation.AUTHORIZATION_ALWAYS) as advised by Apple.
A [locationServicesAuthorization](https://titaniumsdk.com/docs/sdk/Titanium.Geolocation.md#locationServicesAuthorization) value
indicating that the application is authorized to use location services.
### AUTHORIZATION_DENIED
- Type: Number
- Platforms: iPhone, iPad, macOS
- Permission: read-only
A [locationServicesAuthorization](https://titaniumsdk.com/docs/sdk/Titanium.Geolocation.md#locationServicesAuthorization) value
indicating that the application is not authorized to use location services, *or*
location services are disabled.
### AUTHORIZATION_RESTRICTED
- Type: Number
- Platforms: iPhone, iPad, macOS
- Permission: read-only
A [locationServicesAuthorization](https://titaniumsdk.com/docs/sdk/Titanium.Geolocation.md#locationServicesAuthorization) value
indicating that the application is not authorized to use location services *and*
the user cannot change this application's status.
### AUTHORIZATION_UNKNOWN
- Type: Number
- Platforms: iPhone, iPad, macOS
- Permission: read-only
A [locationServicesAuthorization](https://titaniumsdk.com/docs/sdk/Titanium.Geolocation.md#locationServicesAuthorization) value
indicating that the authorization state is unknown.
### AUTHORIZATION_WHEN_IN_USE
- Type: Number
- Platforms: iPhone, iPad, macOS
- Since: Titanium SDK 3.4.0
- Permission: read-only
A [locationServicesAuthorization](https://titaniumsdk.com/docs/sdk/Titanium.Geolocation.md#locationServicesAuthorization) value
indicating that the application is authorized to start most location services only while running in the foreground.
### distanceFilter
- Type: Number
- Platforms: iPhone, iPad, macOS
- Default: `0`
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.
### ERROR_DENIED
- Type: Number
- Platforms: iPhone, iPad, macOS
- Permission: read-only
Error code indicating that the user denied access to the location service.
### ERROR_HEADING_FAILURE
- Type: Number
- Platforms: iPhone, iPad, macOS
- Permission: read-only
Error code indicating that the heading could not be determined.
### ERROR_LOCATION_UNKNOWN
- Type: Number
- Platforms: iPhone, iPad, macOS
- Permission: read-only
Error code indicating that the user's location could not be determined.
### ERROR_NETWORK
- Type: Number
- Platforms: iPhone, iPad, macOS
- Permission: read-only
Error code indicating that the network was unavailable.
### ERROR_REGION_MONITORING_DELAYED
- Type: Number
- Platforms: iPhone, iPad, macOS
- Permission: read-only
Error code indicating that region monitoring is delayed.
### ERROR_REGION_MONITORING_DENIED
- Type: Number
- Platforms: iPhone, iPad, macOS
- Permission: read-only
Error code indicating that region monitoring is denied.
### ERROR_REGION_MONITORING_FAILURE
- Type: Number
- Platforms: iPhone, iPad, macOS
- Permission: read-only
Error code indicating a region monitoring failure.
### hasCompass
- Type: Boolean
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only
Indicates whether the current device supports a compass.
### headingFilter
- Type: Number
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK Android 10.1.0, iPhone 0.8, iPad 0.8
- Default: `0 (No limit on heading updates)`
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.
### headingTime
- Type: Number
- Platforms: Android
- Since: Titanium SDK 10.1.0
- Default: `250`
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](https://developer.android.com/about/versions/12/behavior-changes-12#motion-sensor-rate-limiting)
### lastGeolocation
- Type: String
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK 3.1.2
- Permission: read-only
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.
### locationAccuracyAuthorization
- Type: Number
- Platforms: iPhone, iPad
- Since: Titanium SDK 9.2.0
- Requires: iOS 14.0+
- Permission: read-only
- Default: ``
A value that indicates the level of location accuracy the app has permission to use.
If the value of this property is [Titanium.Geolocation.ACCURACY_AUTHORIZATION_FULL](https://titaniumsdk.com/docs/sdk/Titanium.Geolocation.md#ACCURACY_AUTHORIZATION_FULL),
you can set any constant to [accuracy](https://titaniumsdk.com/docs/sdk/Titanium.Geolocation.md#accuracy). If value is
[Titanium.Geolocation.ACCURACY_AUTHORIZATION_REDUCED](https://titaniumsdk.com/docs/sdk/Titanium.Geolocation.md#ACCURACY_AUTHORIZATION_REDUCED) setting [accuracy](https://titaniumsdk.com/docs/sdk/Titanium.Geolocation.md#accuracy)
to a value other than [Titanium.Geolocation.ACCURACY_REDUCED](https://titaniumsdk.com/docs/sdk/Titanium.Geolocation.md#ACCURACY_REDUCED) has no effect on the location information.
Accepts: `Titanium.Geolocation.ACCURACY_AUTHORIZATION_FULL`, `Titanium.Geolocation.ACCURACY_AUTHORIZATION_REDUCED`
### locationServicesAuthorization
- Type: Number
- Platforms: iPhone, iPad, macOS
- Permission: read-only
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.
Accepts: `Titanium.Geolocation.AUTHORIZATION_ALWAYS`, `Titanium.Geolocation.AUTHORIZATION_AUTHORIZED`, `Titanium.Geolocation.AUTHORIZATION_DENIED`, `Titanium.Geolocation.AUTHORIZATION_RESTRICTED`, `Titanium.Geolocation.AUTHORIZATION_UNKNOWN`, `Titanium.Geolocation.AUTHORIZATION_WHEN_IN_USE`
### locationServicesEnabled
- Type: Boolean
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only
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
- Type: Boolean
- Platforms: iPhone, iPad, macOS
- Since: Titanium SDK 3.1.0
- Default: `false`
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](https://titaniumsdk.com/docs/sdk/Titanium.Geolocation.md#activityType) property.
### showBackgroundLocationIndicator
- Type: Boolean
- Platforms: iPhone, iPad, macOS
- Since: Titanium SDK 7.3.0
- Default: `false`
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.
### showCalibration
- Type: Boolean
- Platforms: iPhone, iPad, macOS
- Default: `true`
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.
### trackSignificantLocationChange
- Type: Boolean
- Platforms: iPhone, iPad, macOS
- Since: Titanium SDK 2.1.2
- Default: `false`
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.
## Methods
### forwardGeocoder
- Platforms: Android, iPhone, iPad, macOS
Resolves an address to a location.
Parameters:
- `address` (String): address to resolve.
- `callback` (Callback, optional): 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: Promise - On SDK 10+, this method will return a `Promise` whose resolved value is equivalent to that passed to the optional callback argument.
### getCurrentHeading
- Platforms: Android, iPhone, iPad, macOS
Retrieves the current compass heading.
Parameters:
- `callback` (Callback, optional): 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: Promise - On SDK 10+, this method will return a `Promise` whose resolved value is equivalent to that passed to the optional callback argument.
### getCurrentPosition
- Platforms: Android, iPhone, iPad, macOS
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:
- `callback` (Callback, optional): 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: Promise - On SDK 10+, this method will return a `Promise` whose resolved value is equivalent to that passed to the optional callback argument.
### hasLocationPermissions
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK 5.1.0
Returns `true` if the app has location access.
Parameters:
- `authorizationType` (Number): Types of geolocation's authorizations. This is an iOS only parameter and is ignored on Android.
Returns: Boolean
### requestLocationPermissions
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK 5.1.0
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](https://titaniumsdk.com/docs/sdk/Titanium.Android.md#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 frequency 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](https://developer.apple.com/library/content/documentation/General/Reference/InfoPlistKeyReference/Articles/CocoaKeys.html)
* [Request Always Authorization](https://developer.apple.com/documentation/corelocation/choosing_the_authorization_level_for_location_services/request_always_authorization)
Parameters:
- `authorizationType` (Number): Types of geolocation's authorizations. This is an iOS only parameter and is ignored on Android.
- `callback` (Callback, optional): 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: Promise - On SDK 10+, this method will return a `Promise` whose resolved value is equivalent to that passed to the optional callback argument.
### requestTemporaryFullAccuracyAuthorization
- Platforms: iPhone, iPad
- Since: Titanium SDK 9.2.0
- Requires: iOS 14.0+
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](https://titaniumsdk.com/docs/sdk/Titanium.Geolocation.md#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](https://titaniumsdk.com/docs/sdk/Titanium.Geolocation.md#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 -
``` xml
NSLocationTemporaryUsageDescriptionDictionary
PurposeKey1
[string](https://titaniumsdk.com/docs/sdk/Global.String.md)
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.
PurposeKey2
[string](https://titaniumsdk.com/docs/sdk/Global.String.md)
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.
```
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:
- `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): Function to call upon user decision to grant authorization.
### reverseGeocoder
- Platforms: Android, iPhone, iPad, macOS
Tries to resolve a location to an address.
The callback receives a [ReverseGeocodeResponse](https://titaniumsdk.com/docs/sdk/ReverseGeocodeResponse.md) object. If the request
is successful, the object includes one or more addresses that are possible matches
for the requested coordinates.
Parameters:
- `latitude` (Number): Latitude to search, specified in decimal degrees.
- `longitude` (Number): Longitude to search, specified in decimal degrees.
- `callback` (Callback, optional): 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: Promise - On SDK 10+, this method will return a `Promise` whose resolved value is equivalent to that passed to the optional callback argument.
## Events
### authorization
- Platforms: iPhone, iPad, macOS
- Since: Titanium SDK 3.4.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.
Event properties:
- `authorizationStatus` (Number): New authorization status for the application.
### calibration
- Platforms: iPhone, iPad, macOS
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
- Platforms: Android, iPhone, iPad, macOS
Fired when an heading update is received.
Event properties:
- `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.
### location
- Platforms: Android, iPhone, iPad, macOS
Fired when a location update is received.
Event properties:
- `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.
### locationupdatepaused
- Platforms: iPhone, iPad, macOS
- Since: Titanium SDK 3.1.0
Fired when location updates are paused by the OS.
This event is fired when [pauseLocationUpdateAutomatically](https://titaniumsdk.com/docs/sdk/Titanium.Geolocation.md#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
- Platforms: iPhone, iPad, macOS
- Since: Titanium SDK 3.1.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.
## Inherited members
7 members are inherited. Each is documented on the type that declares it.
- [Titanium.Proxy](https://titaniumsdk.com/docs/sdk/13.1.0/Titanium.Proxy.md): `addEventListener`, `apiName`, `applyProperties`, `bubbleParent`, `fireEvent`, `lifecycleContainer`, `removeEventListener`
---
- This corpus documents Titanium SDK 13.4.1. Anything here that does not name a version describes 13.4.1.
- Titanium is maintained by TiDev. The Appcelerator toolchain is retired: there is no `appc` CLI, no Appcelerator Studio and no hosted build service. The supported CLI is `titanium` on npm, invoked as `ti`.