Skip to main content

Timezone service

|

The TimezoneService provides functionality for managing and retrieving time zone information. It allows you to transform a UTC Time to a specific time zone, but also provides other details regarding the offset and the timezone.

The TimezoneService object provides methods to get timezone information online (more accurate and takes into account new changes) or offline (faster, works regardless of network access but may be outdated).

  • getTimezoneInfoWithCoordinates and getTimezoneInfoWithTimezoneId methods retrieve timezone information asynchronously.
  • Both methods support an accurateResult parameter that determines whether to use online services (more accurate) or offline data (faster).

The TimezoneResult structure​

The TimezoneResult class represents the result of a time zone lookup operation. It contains the following properties:

MemberTypeDescription
dstOffsetIntDaylight Saving Time (DST) offset in seconds.
utcOffsetIntThe raw UTC offset in seconds, excluding DST. Can be negative.
offsetIntThe total offset in seconds in respect to UTC (dstOffset + utcOffset). Can be negative.
statusETZStatusStatus of the response. See the values below.
timezoneIdString?The timezone identifier in format Continent/City_Name. Examples: Europe/Paris, America/New_York.
localTimeTime?The local time as a Time object representing the local time of the requested timezone.
danger

The TimezoneResult properties are read-only and can only be accessed after a successful timezone lookup operation.

The ETZStatus enum represents the status of a time zone lookup operation. It can have the following values:

  • Success - the request was successful.
  • InvalidCoordinate - the provided geographic coordinates were invalid or out of range.
  • WrongTimezoneId - the provided timezone identifier was malformed or not recognized.
  • WrongTimestamp - the provided timestamp (Time) was invalid or could not be parsed.
  • TimezoneNotFound - no timezone could be found for the given input.

Get timezone info by coordinates​

The getTimezoneInfoWithCoordinates method allows you to retrieve time zone information based on geographic coordinates (latitude and longitude) and a UTC Time object. This can be useful for applications that need to determine the local time zone for a specific location.

Basic usage example​

    val timezoneResult = TimezoneResult()
    val coordinates = Coordinates(55.626, 37.457)
    val utcTime = Time.getUniversalTime() // Current UTC time

    val timezoneListener = ProgressListener.create(
        onCompleted = { errorCode, _ ->
            if (errorCode == GemError.NoError) {
                // Success - access timezone data
                when (timezoneResult.status) {
                    ETZStatus.Success -> {
                        val timezoneId = timezoneResult.timezoneId
                        val offset = timezoneResult.offset // Total offset in seconds
                        val dstOffset = timezoneResult.dstOffset // DST offset in seconds
                        val utcOffset = timezoneResult.utcOffset // UTC offset in seconds
                        val localTime = timezoneResult.localTime

                        // Use the timezone information
                        //displayTimezoneInfo(timezoneId, offset, localTime)
                    }

                    ETZStatus.InvalidCoordinate -> {
                        Log.e("TimezoneService", "Invalid coordinates provided")
                    }

                    ETZStatus.TimezoneNotFound -> {
                        Log.e("TimezoneService", "No timezone found for location")
                    }

                    else -> {
                        Log.e("TimezoneService", "Timezone lookup failed: ${timezoneResult.status}")
                    }
                }
            } else {
                Log.e("TimezoneService", "Request failed: ${GemError.getMessage(errorCode)}")
            }
        },

        postOnMain = true
    )

    // Request timezone information
    // accurateResult = true: Use online service (more accurate, requires internet)
    // accurateResult = false: Use offline data (faster, may be outdated)
    val errorCode = TimezoneService.getTimezoneInfoWithCoordinates(
        timezoneResult = timezoneResult,
        coordinates = coordinates,
        time = utcTime!!,
        listener = timezoneListener,
        accurateResult = true
    )

    if (GemError.isError(errorCode)) {
        Log.e("TimezoneService", "Failed to start timezone request: ${GemError.getMessage(errorCode)}")
    }

Using offline data​

For faster results that don't require internet connectivity, use accurateResult = false:

    val timezoneResult = TimezoneResult()
    val coordinates = Coordinates(55.626, 37.457)
    val utcTime = Time.getUniversalTime()

    val timezoneListener = ProgressListener.create(
        onCompleted = { errorCode, _ ->
            if (errorCode == GemError.NoError && timezoneResult.status == ETZStatus.Success) {
                // Process offline timezone result
                val localTime = timezoneResult.localTime
                val timezoneId = timezoneResult.timezoneId
                // Note: Offline data may be outdated
            }
        },
        postOnMain = true
    )

    // Use offline data for faster response
    TimezoneService.getTimezoneInfoWithCoordinates(
        timezoneResult,
        coordinates,
        utcTime!!,
        timezoneListener,
        accurateResult = false
    )

Get timezone info by timezone ID​

The getTimezoneInfoWithTimezoneId method allows you to retrieve time zone information based on a specific timezone ID and a UTC Time object.

Basic usage example​

    val timezoneResult = TimezoneResult()
    val timezoneId = "Europe/Moscow"
    val utcTime = Time.getUniversalTime()

    val timezoneListener = ProgressListener.create(
        onCompleted = { errorCode, _ ->
            if (errorCode == GemError.NoError) {
                when (timezoneResult.status) {
                    ETZStatus.Success -> {
                        val offset = timezoneResult.offset
                        val localTime = timezoneResult.localTime
                        val dstOffset = timezoneResult.dstOffset

                        // Use the timezone information
                        //processTimezoneData(offset, localTime, dstOffset)
                    }

                    ETZStatus.WrongTimezoneId -> {
                        Log.e("TimezoneService", "Invalid timezone ID: $timezoneId")
                    }

                    else -> {
                        Log.e("TimezoneService", "Timezone lookup failed")
                    }
                }
            } else {
                Log.e("TimezoneService", "Request failed: ${GemError.getMessage(errorCode)}")
            }
        },

        postOnMain = true
    )

    // Request timezone information by ID
    val errorCode = TimezoneService.getTimezoneInfoWithTimezoneId(
        timezoneResult = timezoneResult,
        timezoneId = timezoneId,
        time = utcTime!!,
        listener = timezoneListener,
        accurateResult = true
    )

    if (GemError.isError(errorCode)) {
        Log.e("TimezoneService", "Failed to start timezone request")
    }

Using offline data​

For faster results without internet dependency:

    val timezoneResult = TimezoneResult()

    val timezoneListener = ProgressListener.create(
        onCompleted = { errorCode, _ ->
            if (errorCode == GemError.NoError && timezoneResult.status == ETZStatus.Success) {
                // Process offline result
                val offset = timezoneResult.offset
                val localTime = timezoneResult.localTime
            }
        },
        postOnMain = true
    )

    TimezoneService.getTimezoneInfoWithTimezoneId(
        timezoneResult,
        "Europe/Moscow",
        Time.getUniversalTime()!!,
        timezoneListener,
        accurateResult = false // Use offline data
    )

Working with Time objects​

The Time class provides utilities for creating and manipulating time values:

// Create UTC time
val utcTime = Time.getUniversalTime()

// Create local time
val localTime = Time.getLocalTime()

// Create custom time
val customTime = Time().apply {
    year = 2025
    month = 7
    day = 1
    hour = 6
    minute = 0
    second = 0
}

// Convert to timestamp (milliseconds since epoch)
val timestamp = customTime.asLong()

// Create from timestamp
val timeFromTimestamp = Time().apply {
    fromLong(timestamp)
}
Last updated on