Location time zone detection

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.

Location time zone detection information flow

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