Location time zone detection, available on Android 12 and higher, is an optional automatic time zone detection feature that lets devices use their location and time zone map data to determine the time zone.
Location time zone detection is an alternative mechanism to telephony time zone detection. Because this feature doesn't require telephony, this feature can be supported on devices of various form factors in addition to mobile telephony devices.
The location time zone detection feature consists of the following components in the AOSP platform:
- Time zone detection logic in the system server
A user-accessible option in Settings, introduced in Android 12, to enable users to select between the telephony and location time zone detection mechanisms
A plug-in system for components that perform the location detection and time zone mapping. The plugin is called a Location Time Zone Provider (LTZP) and there can be up to two of them on a device. The platform provides system APIs that must be used to implement an LTZP.
A reference LTZP implementation.
Host tooling to generate a reference dataset from Open Street Map (OSM) data that can be used with the reference implementation.
User privacy
Location time zone detection includes the following user privacy features:
When there is a toggle to select the location algorithm, users can turn off the location algorithm at any time.
Location-derived time zone suggestions aren't shared between users on a device.
Users can control the location detection for time zone detection explicitly through the Date and Time Settings screen. Users don't have to explicitly grant permission through a permission dialog.
Device location information isn't passed to the Android platform services. The following happens instead:
- The time zone detector services are sent time zone IDs by the LTZP, not the device's location. This is the minimal API needed to support location time zone detection.
- System integrators control the operation of individual LTZPs. LTZP implementations can use time zone map data held entirely on the Android device, use servers, or use a hybrid approach.
Feature behavior
The time_zone_detector service determines when to change the device's current
time zone based on suggestions it receives from detection algorithms.
The location_time_zone_manager service is responsible for generating
suggestions for the location algorithm of time_zone_detector. The
location_time_zone_manager service runs in the system server process.
The location_time_zone_manager service doesn't contain any time zone detection
logic. This service is responsible for managing the lifecycle of one or two
LTZP plugins.
When location time zone detection isn't needed, the LTZPs aren't started. This means that the location time zone detection system doesn't ask LTZPs to track the device's location unless they're explicitly required to. Some of the reasons for this behavior include the following:
- Unlike telephony signals that are received passively as part of normal telephony operations, location can be actively requested from Android location providers and can consume additional power.
- Location settings are user scoped and Android must respect the current user's settings.
- Obtaining the device's location is privacy sensitive.
Also, the location_time_zone_manager service makes an uncertain suggestion (if
needed) when the current user changes settings to avoid sharing location
information between users.
As a result of these choices, it takes a few seconds after switching the current algorithm to location, or after switching the current user, before the time zone can be detected. This also depends on the implementations of the LTZPs being used.
The AOSP location time zone detection implementation allows up to two LTZPs, a primary and a secondary LTZP as defined here:
- Primary LTZP
- Runs at all times when the user has allowed the location time zone detection feature to run.
- Secondary LTZP
- Runs if the primary LTZP reports that the time zone is uncertain, reports a permanent failure, or times out during initialization. Stops if the primary LTZP submits a certain suggestion.
As shown in Figure 1, the time_zone_detector service receives time zone
suggestions from the telephony or location algorithm. The location algorithm
receives suggestions from the primary or secondary LTZP.
Figure 1. Location time zone detection information flow.
Device configuration requirements
To support the location time zone feature, devices must be configured with LTZPs that the device can use. Devices require at least one LTZP to be enabled and configured for location time zone detection to be functional and visible to users in Settings.
Device configuration
This section describes how device manufacturers can configure devices to support location time zone detection.
The base AOSP configuration is at
frameworks/base/core/res/res/values/config.xml:
| Configuration key | AOSP value | Description |
|---|---|---|
config_enableGeolocationTimeZoneDetection |
true |
This is the main control for the location time zone detection feature.
The feature is supported by default in AOSP. At least one LTZP must be enabled or configured for the feature to be available to users. Setting the value to false disables the feature entirely for a
small memory saving. |
config_enablePrimaryLocationTimeZoneProvider |
false |
This enables the primary LTZP. |
config_primaryLocationTimeZoneProviderPackageName |
Set this to the package name of the app where the primary provider service can be found. | |
config_enableSecondaryLocationTimeZoneProvider |
false |
This enables the secondary LTZP. |
config_secondaryLocationTimeZoneProviderPackageName |
Set this to the package name of the app where the secondary provider service can be found. |
By default, the AOSP configuration has the
config_enableGeolocationTimeZoneDetection key set to true, enabling support
for the location time zone detection feature. The feature isn't visible to
users initially because AOSP doesn't include an LTZP configuration by default.
However, using this default configuration, device manufacturers can enable and
simulate LTZPs from the command line for testing. (For more information, see
Debug and test.)
LTZP status APIs
In Android 14, the LTZP APIs support the LTZP reporting status information. This enables the LTZP to report issues that the platform might not be able to detect for itself, as the platform time zone detection components aren't directly involved in location or time zone detection in the location algorithm.
The ability to report that the LTZP's behavior has been degraded by the device's
environment is useful when
telephony fallback
mode
is supported. For example, if a third-party LTZP that relies on custom settings
or permissions for its location detection to work is running in a degraded mode
or disabled by the current device settings, the LTZP can report this status
information to internal platform components such as the Settings app through the
reportSuggestion
method. The Settings app can then notify users through customizable strings or
customizations that there are settings that must change for the location
algorithm to work well or at all.
For more information on the statuses that the LTZP can report, see
TimeZoneProviderStatus.
LTZP configuration and deployment
When configuring an LTZP, read the instructions in the source code for
frameworks/base/core/java/android/service/timezone/TimeZoneProviderService.java.
The Javadoc comments provide details on the service, permissions needed, and
other configuration.
To configure an LTZP, device manufacturers must choose an app process to host the LTZP's service. Having a dedicated process for an LTZP is a high overhead; ideally, the app process chosen is one that is running at all times, such as the system server.
On devices with
modular system components
(modules), consider the interaction between the geo data used by the LTZP and
the time zone rules (tzdb) carried in the
Time Zone Data module
(com.android.tzdata). Updates to one without updates to the other are likely
to cause version skew issues. For more information, see
Feature adoption considerations.
AOSP reference LTZP
AOSP contains a reference LTZP implementation under
packages/modules/GeoTZ.
This reference implementation uses AOSP APIs to determine the device's location
and uses an on-device data file to map the location to a set of time zone IDs.
A reference data set derived from other open source projects is included with the source code. For more details, see README.md and the various LICENSE files.
Debug and test
The following section describes shell commands for debugging and testing the location time zone detection feature.
Interact with the location_time_zone_manager service
When the location algorithm is supported on a device running
Android 12 and higher,
Android instantiates the location_time_zone_manager service at boot time.
To dump the current state of the location_time_zone_manager, use:
adb shell cmd location_time_zone_manager dump
To see an extensive set of command line options to assist with testing, use:
adb shell cmd location_time_zone_manager help
The help output also describes the device_config service properties that can
be used to affect the behavior of the time_zone_detector for testing or in
production. For more information, see
Configure a device using the device_config
service.
LTZP implementations can provide their own debugging or testing support. For example, you can use the following command to debug the AOSP reference LTZP when it's registered in the system server process:
adb shell dumpsys activity service android/com.android.timezone.location.provider.OfflineLocationTimeZoneProviderService