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 class 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).

• getTimezoneInfo methods retrieve timezone information either by geographic coordinates or by timezone ID. Users can choose to query Magic Lane’s online services for accurate data or use the less precise offline resource.

warning

The offline timezone resource must be periodically updated in order to provide relevant results.

The TimezoneResult structure

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

Methods	Type	Description
getDstOffset	int	Daylight Saving Time (DST) offset in seconds.
getUtcOffset	int	The raw UTC offset, excluding DST. Can be negative. In seconds.
getOffset	int	The total offset in respect to UTC (dstOffset + utcOffset). Can be negative. In seconds.
getStatus	ETZStatus	Status of the response. See the values below.
getTimezoneId	String	The timezone identifier in format Continent/City_Name. Examples: Europe/Paris, America/New_York.
getLocalTime	Time	The local time as a Time object, but representing the local time of the requested timezone, affected by offsets. Use the day, hour, minute, second getters from the Time object.

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

• TZ_Success - the request was successful.
• TZ_InvalidCoordinate - the provided geographic coordinates were invalid or out of range.
• TZ_WrongTimezoneId - the provided timezone identifier was malformed or not recognized.
• TZ_WrongTimestamp - the provided timestamp (Time) was invalid or could not be parsed.
• TZ_TimezoneNotFound - no timezone could be found for the given input.
• TZ_SuccessUsingObsoleteData - the request succeeded but the service had to fall back to obsolete/outdated timezone data. Relevant when using accurateResult set to false. Please update the SDK.

Get timezone info by coordinates

Get timezone info by coordinates online

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

TimezoneResult result;
TimezoneService().getTimezoneInfo( result,
    Coordinates(55.626, 37.457),
    Time::getUniversalTime(),   // <-- now time in UTC
    yourProgressListenerImpl
);

Get timezone info by coordinates offline

The getTimezoneInfo method allows you to retrieve time zone information based on geographic coordinates (latitude and longitude) and an UTC Time without making an online request. This can be useful for applications that need to determine the local time zone for a specific location without relying on network access. Simply set accurateResult parameter to true.

TimezoneResult result;
TimezoneService().getTimezoneInfo( result,
    Coordinates(55.626, 37.457),
    Time::getUniversalTime(),   // <-- now time in UTC
    ProgressListener(), // <-- progress listener not needed in this case. The result is returned right away.
    true
);

Get timezone info by timezone ID

Get timezone info by timezone ID online

The getTimezoneInfo method with timezoneId allows you to retrieve time zone information based on a specific timezone ID and an UTC Time.

TimezoneResult result;
TimezoneService().getTimezoneInfo( result,
    "Europe/Moscow",
    Time::getUniversalTime(),   // <-- now time in UTC
    yourProgressListenerImpl
);

Get timezone info by timezone ID offline

The getTimezoneInfo method allows you to retrieve time zone information based on a specific timezone ID and an UTC Time without making an online request. This can be useful for applications that need to determine the local time zone for a specific location without relying on network access.

TimezoneResult result;
TimezoneService().getTimezoneInfo( result,
    "Europe/Moscow",
    Time::getUniversalTime(),   // <-- now time in UTC
    ProgressListener(), // <-- progress listener not needed in this case. The result is returned right away.
    true
);