Time overview

This page describes how time and time zone detection works on Android. This includes how Android automatically detects time and time zones, configuration options for device manufacturers, and testing information.

Overview of time and time zones

To determine a user's local time for display in locations such as the status bar, Android keeps track of two related but independent states:

• The current Unix epoch time
• The current time zone

The current Unix epoch time and current time zone are device-wide states, meaning that they are shared by all users of a device.

The current Unix epoch time isn't a fixed value. It updates automatically to reflect the passage of time. Besides the normal passage of time, the current Unix epoch time of a device is adjusted if it's found to be incorrect, for example, after a device loses power.

The current time zone determines the adjustment to be made to convert the current Unix epoch time into a local time. For example, during summer in Los Angeles, the device subtracts 7 hours from the current Unix epoch time, and in winter it subtracts 8 hours.

To support these local time calculations, all Android devices have a database of all global time zone rules. For more information on time zone rules, see Time Zone Rules.

When a user travels to a new location that uses a different time zone, the current Unix epoch time doesn't need to be adjusted but the user typically wants to see the local time rather than the time in their previous location. Changing the current time zone ensures that the correct offset is applied to the current Unix epoch time to display the correct local time for the new location.

AOSP allows users to independently control whether the time and time zone are set automatically for them through the following mechanisms.

• Automatic time detection: Ensures that the device has the correct current Unix epoch time.
• Automatic time zone detection: Ensures that the device has the correct current time zone.

Automatic time detection

This section provides an overview of the time_detector service that manages automatic time detection, user controls, configuration options, and testing details.

The time_detector service

The time_detector service, present on devices running Android 10 or higher, manages automatic time detection. It adjusts the device's current Unix epoch time as needed when automatic time detection is enabled.

The time_detector service is always in one of two states: uncertain or certain. The service's certain or uncertain state is determined by time suggestions that it receives from various sources.

When the time_detector service is certain, meaning that it has received a suggestion with Unix epoch time information, it overrides the current Unix epoch time if the time suggestion is different from the current Unix epoch time.

When time_detector is uncertain, it doesn't override the current time. The uncertain state usually means the time_detector service hasn't received time suggestions. The time_detector service also becomes uncertain if suggestions it has received are considered too old to be used. The age of suggestions is considered because adjustments using old Unix epoch time suggestions rely on the elapsed realtime clock on the device, which is assumed to be inaccurate over long periods.

To establish the current Unix epoch time automatically, a device has various sources it can use. These are called origins in this document. The time_detector service treats sequences of suggestions as distinct based on their origin.

The time_detector service is stateful, which means that it keeps a record of the most recent suggestion made by each origin. New suggestions are made to time_detector if an origin has more recent Unix epoch time information available. The time_detector service reevaluates new and existing suggestions and updates the device state when suggestions are received.

Although UTC time is agreed upon internationally, there are various reasons why establishing the current Unix epoch time isn't always straightforward for an Android device:

• Unix epoch time is a subtly different timekeeping system from UTC time. Converting between the two requires knowledge of when leap seconds occur and how they are handled by origins.
• Origins might be available only at certain times or under certain circumstances. For example, if the origin requires network connectivity, it might be available only while the device is connected to the internet.
• The origins might be inaccurate or imprecise, or have errors. For example, if a telephony cell tower isn't tracking "universal time" correctly, the telephony origin might provide inaccurate time suggestions.
• There might be inaccuracies introduced while obtaining the Unix epoch time. For example, a network delay, buffering, or process scheduling might cause the Unix epoch time to be inaccurate.
• The reference clock used to adjust a suggestion for elapsed time since the suggestion was received might be inaccurate.

There are two main time detection origins configured for use by default in AOSP:

• Network: Uses Network Time Protocol (NTP) time servers.
• Telephony: Uses Network Identity and Time Zone (NITZ) telephony signals.

Both telephony and network origins require connectivity to external networks, which are not always available.

Starting with Android 12, Android also supports the following origins, which are not configured for use by default:

• GNSS: Uses the GPS location provider to obtain a time from a GNSS source.
• External: Generic origin that allows device manufacturers to integrate their own source of Unix epoch time.

Time settings

Users can enable automatic time detection in System > Date and Time in the AOSP Settings app.

Figure 1. Automatic time detection in Settings.

The following table describes the user controls for time detection in the AOSP Settings app.

When the user enters time manually, they enter their local time, not Unix epoch time. The current Unix epoch time is calculated by using the current time zone to derive a Unix epoch time.

Configuration

Device manufacturers can configure the time_detector service in various ways, such as which origins to use and how to prioritize the signals from them.

Origin prioritization

From Android 12, device manufacturers can change the core/res/res/values/config.xmlconfiguration file to specify which time origins to include in automatic time detection, and the priority in which time_detector considers these origins.

For devices running Android 11 or lower, origin priority is hardcoded to["telephony", "network"], meaning that telephony suggestions are prioritized above network suggestions.

The default AOSP configuration is as follows:

<!-- Specifies priority of automatic time sources. Suggestions from higher entries in the list
     take precedence over lower ones.
     See com.android.server.timedetector.TimeDetectorStrategy for available sources. -->
<string-array name="config_autoTimeSourcesPriority">
    <item>network</item>
    <item>telephony</item>
</string-array>

In Android 12, network and telephony suggestions are configured as origins to use by default. Network time suggestions are prioritized above telephony time suggestions. Device manufacturers can change the order of the origins to revert to the behavior in Android 11 or lower, where telephony is given a higher priority.

By default, if the highest priority valid suggestion matches the device's current system clock time to within a couple of seconds, the device time won't be changed. This is to avoid creating work for installed apps that listen to the ACTION_TIME_CHANGED intent.

The allowed origin values are:

• Network
• Telephony
• GNSS
• External

Allowed time bounds

Android 14 introduces an upper time bound for time suggestions received by the time_detector service. If the device supports 32-bit processes, the framework sets an upper time bound to prevent the device from using a time suggestion that could trigger the Y2038 issue.

Android 12 introduced a lower time bound that's used to validate time suggestions received by the time_detector service. The lower time bound value used for automated suggestions is set from the build timestamp. This works on the principle that a valid time can't be before the device's system image was built. If a time suggestion is before the lower time bound, the time_detector service discards the suggestion because it can't be valid if the build timestamp is correct.

For devices running Android 11 or lower, the time_detector service doesn't validate incoming Unix epoch time suggestions.

Time debugging and testing

This section provides information about how to debug and test the behavior of the time_detector service and other components that are shared by all origins.

Interact with the time_detector service

To view the time_detector service's configuration and state of the time_detector service, use:

adb shell cmd time_detector dump

To see additional commands for debugging and testing time zone detection, use:

adb shell cmd time_detector help

The help output also describes the device_config service properties that can be used to affect the behavior of time_detector for testing or in production. For details, see Configuring a device using the device_config service.

To validate automatic time detection, testers must be aware which origins the time_detector service is using. The following is an example of the output from the adb shell cmd time_detector dump command, with the information about the current origin and service state in bold:

$ adb shell cmd time_detector dump

TimeDetectorStrategy:
  mLastAutoSystemClockTimeSet=null
  mEnvironment.isAutoTimeDetectionEnabled()=true
  mEnvironment.elapsedRealtimeMillis()=23717241
  mEnvironment.systemClockMillis()=1626707861336
  mEnvironment.systemClockUpdateThresholdMillis()=2000
  mEnvironment.autoTimeLowerBound()=2021-07-19T07:48:05Z(1626680885000)
  mEnvironment.autoOriginPriorities()=[network,telephony]
  Time change log:
    ...
  Telephony suggestion history:
    ...
  Network suggestion history:
    ...
  Gnss suggestion history:
    ...
  External suggestion history:
    ...

The information can be interpreted as follows:

The time change log indicates occasions when the time_detector service has changed the current Unix epoch time of the device.

The suggestion history information indicates what suggestions have been made by each origin.

Automatic time zone detection

This section provides an overview of the time_zone_detector service that manages automatic time zone detection, user controls in settings, telephony and location time zone detection, and testing details.

The time_zone_detector service

The time_zone_detector service, present on devices running Android 11 or higher, manages automatic time zone detection. It adjusts the device's current time zone as needed when automatic time zone detection is enabled.

When automatic time zone detection is enabled, time_zone_detector can be in one of two states: uncertain and certain.

When the time_zone_detector service is in the certain state, this means the time_zone_detector service has received strong time zone information, which can cause it to override the current time zone. When it is uncertain, this means it has received no information or only low-confidence information, which means it won't override the current time zone.

The time_zone_detector service's certain states can include ones where time_zone_detector has no time zone information to use, or where it has multiple time zones to choose between. These states are as follows:

• A certain state with zero time zones is entered when the device is somewhere without a time zone, such as in international waters or in a disputed area. This state is similar to an uncertain state, but indicates that time_zone_detector doesn't need to take further action to try to determine the time zone.
• A certain state with multiple time zones is entered where there is ambiguity or border conditions. In this state, if the current time zone is one of the time zones time_zone_detector is certain about, the current time zone is left as it is. Otherwise, one of the available time zones is used. This gives time_zone_detector an element of stickiness if the user has manually selected their time zone previously or as the device approaches a border.

The time_zone_detector service's certain or uncertain state is determined by time zone suggestions that are sent by an algorithm.

Generally, suggestions come in two types that closely match the possible states of time_zone_detector: certain and uncertain. The following are examples of suggestion types:

• type = uncertain, zoneIds = []

  • The algorithm doesn't know what the time zone is.

• type = certain, zoneIds = ["Europe/London"]

  • The algorithm is certain the zone is Europe/London.

• type = certain, zoneIds = []`

  • The algorithm is certain, but there's no zone ID associated with the current location.

• type = certain, zoneIds = ["America/Denver", "America/Phoenix"]

  • The algorithm is certain that the answer is one of two zones, but can't choose between "America/Denver" and "America/Phoenix".

The time_zone_detector service treats sequences of suggestions as distinct based on their algorithm. Depending on the algorithm, suggestions might also contain metadata that indicates how certain the algorithm is.

The time_zone_detector service is stateful, which means that it keeps a record of the most recent suggestion made by each algorithm. New suggestions are sent to the time_zone_detector service if a previous suggestion is no longer correct; that is, if an algorithm now has a different suggestion, or if it has lost the ability to detect the time zone. The time_zone_detector service reevaluates new and existing suggestions and updates the device state when suggestions are received.

Android supports two algorithms for time zone detection:

• Telephony
• Location

The time_zone_detector service typically uses a single algorithm to determine the time zone. When the location algorithm is supported on a device, the algorithm the device uses is determined based on the Time zone settings configured by the user. When the algorithm in use becomes uncertain of the time zone, time_zone_detector doesn't usually use suggestions from a different algorithm. Suggestions associated with algorithms that aren't in use can be held in memory by time_zone_detector, but they aren't used unless the algorithm changes. When the user changes the settings for automatic time zone detection and the algorithm changes, the most recent suggestion available for the new algorithm is used.

For details about the situation where multiple algorithms are used to determine the time zone, see Telephony fallback mode.

Telephony fallback mode

On devices running Android 13 and higher, the time_zone_detector service supports the telephony fallback mode. This mode lets Android use telephony detection suggestions temporarily in situations where location detection is unable to detect the time zone or where location detection takes longer to detect the time zone than telephony detection.

The telephony fallback mode applies to devices where both telephony and location detection are supported, and where the user has enabled Use location to set time zone in Time zone settings. The mode is enabled automatically when a device is rebooted, and when airplane mode is disabled.

In Android 14 and higher, telephony fallback can be triggered through the LTZP status reporting APIs, that is, if a LTZP reports it is uncertain and its ability to detect location or time zone is degraded by its environment, telephony fallback mode is triggered.

When in telephony fallback mode, the time_zone_detector service uses telephony suggestions as if location detection is disabled until the location algorithm makes a certain suggestion. After receiving a certain suggestion, the telephony fallback mode is disabled and location suggestions are used exclusively.

For configuration details for the telephony fallback mode, see Time zone detection configuration.

Time zone settings

Users can enable and configure the settings for automatic time zone detection in the AOSP Settings app.

Figure 2. Automatic time zone detection in Settings.

The following table describes the user controls for time zone detection in the AOSP Settings app.

The following provides an overview of the device behavior for time zone detection given the settings chosen by the user:

• [Date and Time] Set time zone automatically: OFF

  • The user must manually select the time zone.

• [Date and Time] Set time zone automatically: ON

  • [Location] Use location: OFF

    • Telephony signals are used to detect the time zone.

  • [Location] Use location: ON

    • [Date and Time] Use location to set time zone: ON

      • Location is used to detect the time zone.

    • [Date and Time] Use location to set time zone: OFF

      • Telephony signals are used to detect the time zone.

Multiple user devices

Because several of the settings involved are scoped to the current user, the time zone detection behavior of a device can change when the current user changes on a multi-user Android device.

The Use location to set time zone toggle is scoped to the current user and isn't restricted by device policy, meaning that users can always change its value, even when the Set time zone automatically toggle is off or if other time or time zone controls are restricted by the Device Policy Controller.

 Devices that support only the location time zone detection algorithm

This section describes the behavior for devices that support only the location algorithm.

• Android 14 and higher

  • The Use location option isn't shown to users in the AOSP Settings app and the device behaves as if the Use location option is enabled.
  • The value of the user-scoped SettingsProvider setting location_time_zone_detection_enabled is ignored. This value records the user's preference on other types of devices.

• Android 12 or Android 13

  • The Use location option is visible to users in the AOSP Settings app and users can disable the option. If the option is disabled, the device won't detect the time zone automatically.

Behavior when changing to and from automatic detection

When the user switches time zone detection from manual to automatic, time_zone_detector might already be certain of the current time zone. If so, as the user enables automatic detection, the device's time zone might be changed at the same time to match the time_zone_detector service's opinion.

Similarly, when the user makes a change in Settings that result in a change to the time_zone_detector service's current algorithm, time_zone_detector might already have received suggestions for the new algorithm and so the device's time might be changed to match the time_zone_detector service's opinion immediately.

Telephony time zone detection

Telephony time zone detection uses telephony signals to determine the current time zone. For more information, see Telephony Time Zone Detection.

Location time zone detection

Location time zone detection is available on Android 12 or higher. It's an optional automatic time zone detection feature that enables devices to use their location to determine the current time zone.

The location_time_zone_manager service, introduced in Android 12, runs in the system server and contains the code responsible for submitting location algorithm suggestions to the time_zone_detector service. For more information, see Location Time Zone Detection.

Feature adoption considerations

This section describes aspects of the location time zone detection feature to help a device manufacturer determine whether to adopt the feature on a device.

Compare telephony and location detection

The following table provides a comparison of the advantages and disadvantages of using location rather than telephony signals for time zone detection.

User privacy

A user's preferred time zone is usually determined by their geographic location. Location is sensitive data. Users might be concerned about knowledge of their location being shared as part of time zone detection. Unrelated to time zone detection, all apps running on a device can read the device's current time zone without requiring an Android permission, and apps can infer an imprecise idea of the device's location from this information.

More specifically, time zone detection can work through passive or active means:

• Passive: Something in the device's environment tells the device the time zone to use in that environment.
• Active: The device has to work out the time zone for itself and depending on users' privacy settings and their consent, obtains the device's location to do so. It can then share its location with external services. See discussion below for details on user privacy and consent.

Passive detection, such as with the telephony algorithm, has no additional privacy implications for users.

Active detection, such as with the location algorithm, involves determining the device's location, which users might not want to agree to, and the location could be sent over a network in order to determine the time zone ID.

Android's approach to user privacy for time zone detection gives the user the ability to individually disable algorithms that are expected to be active. Additionally, the AOSP platform code doesn't deal directly with location itself: location detection and mapping location to time zone IDs are left to plug-in components configured by device manufacturers.

For more details on user privacy features, see Location Time Zone Detection.

Configuration

Device manufacturers can configure the time_zone_detector service to change its behavior. This section describes configuration options for the general behavior of the time_zone_detector service. For configuration details for the telephony and time zone detection algorithms, see Telephony Time Zone detection and Location Time Zone Detection.

The base AOSP configuration is at frameworks/base/core/res/res/values/config.xml.

 Altering device default behavior

In AOSP, automatic time zone detection is enabled by default with the auto_time_zone setting set to true. To disable automatic time detection by default, set the value of def_auto_time_zone defined in frameworks/base/packages/SettingsProvider/res/values/defaults.xml to false.

When restoring a backup from another device, the framework updates the value of the auto_time_zone setting by default. If you want to ensure that this setting isn't restored from a backup, include auto_time_zone in the restore_blocked_global_settings array defined in frameworks/base/packages/SettingsProvider/res/values/blocked_settings.xml.

Time zone debugging and testing

This section provides information about how to debug and test the behavior of the time_zone_detector service and other components that are shared by all algorithms.

Configure a device using the device_config service

The device_config service is a mechanism used on Android to configure modifiable behavior using values that are typically pulled from a remote server by proprietary (non-AOSP) code. When using device_config values for testing, especially during long running manual tests, the device might synchronize the flags, which would reset the flags and clear the values set for testing.

In Android 12 or higher, to temporarily prevent flag synchronization, use:

adb shell cmd device_config set_sync_disabled_for_tests persistent

To restore flag synchronization after tests, use:

adb shell cmd device_config set_sync_disabled_for_tests none

After restoring flag synchronization, reboot the device.

For more information, use $ adb shell cmd device_config help.

Interact with the time_zone_detector service

To view the time_zone_detector configuration and state of the time_zone_detector service, use:

adb shell cmd time_zone_detector dump

To see additional commands for debugging and testing time zone detection, use:

adb shell cmd time_zone_detector help

The help output also describes the device_config service properties that can be used to affect the behavior of the time_zone_detector service for testing or in production. For details, see Configuring a device using the device_config service.

To validate time zone detection, testers must be aware which algorithm the time_zone_detector is using. To understand and influence the current algorithm of the time_zone_detector, use one of the following options:

• Check visually through the Settings UI. For more information, see Time zone settings.

• Use the command line through adb:

  • To dump time_zone_detector state, use adb shell cmd time_zone_detector dump
  • To alter device setting, use other time_zone_detector commands. For more information, use adb shell cmd time_zone_detector help.

The following is an example of the output from the adb shell cmd time_zone_detector dump command, with the information about the current algorithm and service state in bold:

$ adb shell cmd time_zone_detector dump
TimeZoneDetectorStrategy:
  mEnvironment.getCurrentUserId()=0
  mEnvironment.getConfiguration(currentUserId)=ConfigurationInternal{mUserId=0, mUserConfigAllowed=true, mTelephonyDetectionSupported=true, mGeoDetectionSupported=true, mAutoDetectionEnabled=true, mLocationEnabled=true, mGeoDetectionEnabled=true}
  [Capabilities=TimeZoneCapabilitiesAndConfig{mCapabilities=TimeZoneDetectorCapabilities{mUserHandle=UserHandle{0}, mConfigureAutoDetectionEnabledCapability=40, mConfigureGeoDetectionEnabledCapability=40, mSuggestManualTimeZoneCapability=30}, mConfiguration=TimeZoneConfiguration{mBundle=Bundle[{geoDetectionEnabled=true, autoDetectionEnabled=true}]}}]
  mEnvironment.isDeviceTimeZoneInitialized()=true
  mEnvironment.getDeviceTimeZone()=Europe/London
  Time zone change log:
  Manual suggestion history:
...
  Geolocation suggestion history:
...
  Telephony suggestion history:
...

The information can be interpreted as follows:

The suggestion history information indicates what suggestions have been made through Settings (manual), and by the telephony and location algorithms.