getTimezoneInfoFromCoordinates static method

ProgressListener? getTimezoneInfoFromCoordinates({ required Coordinates coords, required DateTime time, void onComplete(GemError error, TimezoneResult? result)?, })

Asynchronously retrieves timezone information for a coordinate and an UTC timestamp.

Performs an online lookup and returns progress via a ProgressListener. The supplied onComplete callback is invoked once the operation finishes.

Parameters

• coords: Geographic coordinates (latitude/longitude) to resolve.
• time: Instant to resolve (must be provided as a UTC DateTime).
• onComplete: Function called when the operation completes. The function is called with:
  • GemError.success for error and a non-null TimezoneResult for result when the operation completed successfully.
  • GemError.internalAbort for error and null for result when a parsing failure or server-side error occurred.

Returns

• A ProgressListener if the asynchronous operation was started; null if the operation could not be started. When null the specific failure can be inspected via ApiErrorService.apiError.

Example

TimezoneService.getTimezoneInfoFromCoordinates(
  coords: Coordinates.fromLatLong(55.626, 37.457),
  time: DateTime.utc(2025, 7, 1, 6, 0),
  onComplete: (err, result) {
    if (err == GemError.success) {
      print(result!.timezoneId);
    } else {
      print('Error: $err');
    }
  },
);

See also:

• TimezoneResult - The result object that exposes the status and offsets.
• getTimezoneInfoFromCoordinatesSync - Synchronous version of this method.

Implementation

static ProgressListener? getTimezoneInfoFromCoordinates({
  required final Coordinates coords,
  required final DateTime time,
  final void Function(GemError error, TimezoneResult? result)? onComplete,
}) {
  final TimezoneResult result = TimezoneResult.create();
  final EventDrivenProgressListener listener = EventDrivenProgressListener();
  GemKitPlatform.instance.registerEventHandler(listener.id, listener);

  listener.registerOnCompleteWithData((
    final int err,
    final String hint,
    final Map<dynamic, dynamic> json,
  ) {
    GemKitPlatform.instance.unregisterEventHandler(listener.id);
    if (err == 0) {
      onComplete?.call(GemErrorExtension.fromCode(err), result);
    } else {
      onComplete?.call(GemErrorExtension.fromCode(err), null);
    }
  });
  final OperationResult resultString = staticMethod(
    'TimezoneService',
    'getTimezoneInfoCoords',
    args: <String, dynamic>{
      'timezoneResult': result.pointerId,
      'coords': coords,
      'time': time.millisecondsSinceEpoch,
      'progressListener': listener.id,
    },
  );
  final GemError errCode = GemErrorExtension.fromCode(resultString['result']);
  if (errCode != GemError.success) {
    onComplete?.call(errCode, null);
    return null;
  }
  return listener;
}