Timezone service

_|

The TimezoneService provides functionality for managing and retrieving time zone information. It allows you to transform a UTC DateTime 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).

• getTimezoneInfoFromCoordinates and getTimezoneInfoFromTimezoneId methods retrieve timezone information from an online service.
• getTimezoneInfoFromCoordinatesSync and getTimezoneInfoFromTimezoneIdSync methods provide similar functionality but use built-in timezone data, which may be outdated. A SDK update is required once in a while to refresh timezone data.

The TimezoneResult structure

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

Member	Type	Description
dstOffset	number	Daylight Saving Time (DST) offset in seconds.
utcOffset	number	The raw UTC offset in seconds, excluding DST. Can be negative.
offset	number	The total offset in seconds in respect to UTC (dstOffset + utcOffset). Can be negative.
status	TimeZoneStatus	Status of the response. See the values below.
timezoneId	string	The timezone identifier in format Continent/City_Name. Examples: Europe/Paris, America/New_York.
localTime	Date	The local time as a UTC Date object, but representing the local time of the requested timezone, affected by offsets. Use the getDate(), getHours(), getMinutes(), getSeconds() methods from the Date object.

warning

The localTime returned via the TimezoneService methods is returned as a UTC Date object, but represents the local time in the specified time zone.

The TimeZoneStatus 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 (DateTime) was invalid or could not be parsed.
• timezoneNotFound - no timezone could be found for the given input.
• successUsingObsoleteData - the request succeeded but the service had to fall back to obsolete/outdated timezone data. Relevant when using getTimezoneInfoFromCoordinatesSync and getTimezoneInfoTimezoneIdSync. Please update the SDK.

Get timezone info by coordinates

Get timezone info by coordinates online

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

import { TimezoneService, Coordinates, GemError, TimezoneResult } from '@magiclane/maps-sdk';

TimezoneService.getTimezoneInfoFromCoordinates({
  coords: new Coordinates({ latitude: 55.626, longitude: 37.457 }),
  time: new Date(Date.UTC(2025, 6, 1, 6, 0)),   // <-- This is always the Date in UTC
  onComplete: (error: GemError, result?: TimezoneResult) => {
    if (error !== GemError.success) {
      // The request failed, handle the error
    } else {
      // Do something with the result
    }
  }
});

Get timezone info by coordinates offline

The getTimezoneInfoFromCoordinatesSync method allows you to retrieve time zone information based on geographic coordinates (latitude and longitude) and an UTC Date 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.

import { TimezoneService, Coordinates, TimezoneResult } from '@magiclane/maps-sdk';

const result: TimezoneResult | null = TimezoneService.getTimezoneInfoFromCoordinatesSync({
  coords: new Coordinates({ latitude: 55.626, longitude: 37.457 }),
  time: new Date(Date.UTC(2025, 6, 1, 6, 0)), // <-- Always in UTC
});

Get timezone info by timezone ID

Get timezone info by timezone ID online

The getTimezoneInfoFromTimezoneId method allows you to retrieve time zone information based on a specific timezone ID and an UTC Date.

import { TimezoneService, GemError, TimezoneResult } from '@magiclane/maps-sdk';

TimezoneService.getTimezoneInfoFromTimezoneId({
  timezoneId: 'Europe/Moscow',
  time: new Date(Date.UTC(2025, 6, 1, 6, 0)), // <-- Always in UTC
  onComplete: (error: GemError, result?: TimezoneResult) => {
    if (error !== GemError.success) {
      // The request failed, handle the error
    } else {
      // Do something with the result
    }
  },
});

Get timezone info by timezone ID offline

The getTimezoneInfoFromTimezoneIdSync method allows you to retrieve time zone information based on a specific timezone ID and an UTC Date 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.

import { TimezoneService, TimezoneResult } from '@magiclane/maps-sdk';

const result: TimezoneResult | null = TimezoneService.getTimezoneInfoTimezoneIdSync({
  timezoneId: 'Europe/Moscow',
  time: new Date(Date.UTC(2025, 6, 1, 6, 0)), // <-- Always in UTC
});