NAME

Geo::Location::TimeZoneFinder - Map geographic coordinates to time zone names

VERSION

version 1.001

SYNOPSIS

  use Geo::Location::TimeZoneFinder;

  my $finder = Geo::Location::TimeZoneFinder->new(
    file_base => 'combined-shapefile');
  my @time_zones = $finder->time_zones_at(lat => $lat, lon => $lon);

DESCRIPTION

A Perl module that maps geographic coordinates to time zone names, such as "Asia/Shanghai". The module uses database files that are published by the Timezone Boundary Builder project.

SUBROUTINES/METHODS

new

  my $finder = Geo::Location::TimeZoneFinder->new(
    file_base => 'combined-shapefile');

The "file_base" parameter is the base path name for your database files. The extensions .dbf and .shp will be added to the base path name.

Returns a new object. Dies on invalid parameters and file read errors.

time_zones_at

  my @time_zones =
    $finder->time_zones_at(latitude => $lat, longitude => $lon);
  my $time_zone = $finder->time_zones_at(lat => $lat, lon => $lon);

Returns the names of the time zones at the coordinates given by the named parameters "latitude" und "longitude". In scalar context, only one name is returned.

The parameters "latitude" und "longitude" can be abbreviated to "lat" and "lon". The latitude and longitude must be in the ranges -90 to 90 and -180 to 180, respectively.

Dies on invalid parameters and file read errors.

The time zone names correspond to the names in the IANA time zone database, which is used by most Unix systems.

There is usually one time zone in a location, but there are disputed areas with multiple time zones as well as locations on boundaries, such as the North Pole at latitude 90° and the International Date Line at longitude 180°.

time_zone_at

  my $time_zone = $finder->time_zone_at(lat => $lat, lon => $lon);

An alias for time_zones_at that always returns a single value.

index

  for my $shape (@{$finder->index}) {
    my ($x_min, $y_min, $x_max, $y_max) = @{$shape->{bounding_box}};
    my $file_offset = $shape->{file_offset};
    my $time_zone   = $shape->{time_zone};
  }

Returns the internal index that is used to look up boundaries in the shape file.

DIAGNOSTICS

The "file_base" parameter is mandatory

The constructor was called without a filename base.

The "latitude" parameter is mandatory

No "latitude" parameter was given.

The "longitude" parameter is mandatory

No "longitude" parameter was given.

The "latitude" parameter N is not a number between -90 and 90

The latitude must be a number between -90 and 90.

The "longitude" parameter N is not a number between -180 and 180

The longitude must be a number between -180 and 180.

Error opening "FILE"

A file cannot be opened.

Error reading "FILE"

A file cannot be read.

Cannot set file position to N in "FILE"

The position in a file cannot be set.

Expected N records, got M in "FILE"

The number of records does not match the information in the file's header or the number of records in another file.

CONFIGURATION AND ENVIRONMENT

None.

DEPENDENCIES

Requires the file timezones.shapefile.zip from https://github.com/evansiroky/timezone-boundary-builder. The zip archive must be extracted to a directory.

INCOMPATIBILITIES

None.

EXAMPLES

Most Unix systems accept time zone names in the environment variable TZ.

  use Geo::Location::TimeZoneFinder;

  my $finder = Geo::Location::TimeZoneFinder->new(
    file_base => 'combined-shapefile');

  my $tz   = $finder->time_zone_at(lat => 39.916, lon => 116.383);
  my @time = do { local $ENV{TZ} = ":$tz"; localtime };

Speed up repeated lookups by using a cache.

  use Geo::Location::TimeZoneFinder;
  use Mojo::Cache;

  my $cache  = Mojo::Cache->new;
  my $finder = Geo::Location::TimeZoneFinder->new(
    file_base => 'combined-shapefile');

  sub time_zone_at {
    my %args = @_;

    my $lat = $args{lat};
    my $lon = $args{lon};
    my $key = "$lat,$lon";
    my $tz  = $cache->get($key);
    if (!defined $tz) {
      $tz = $finder->time_zone_at(lat => $lat, lon => $lon);
      $cache->set($key, $tz);
    }
    return $tz;
  }

BUGS AND LIMITATIONS

This module uses the point-in-polygon algorithm described in [1], which is very accurate but "cannot solve the problem of instability that can result from the comparison operations of floating-point numbers".

[1] Jianqiang Hao, Jianzhi Sun, Yi Chen, Qiang Cai, and Li Tan. "Optimal Reliable Point-in-Polygon Test and Differential Coding Boolean Operations on Polygons". Symmetry, 10, 2018.

AUTHOR

Andreas Vögele <voegelas@cpan.org>

LICENSE AND COPYRIGHT

Copyright (C) 2023 Andreas Vögele

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Geo::Location::TimeZoneFinder

perl -MCPAN -e shell
install Geo::Location::TimeZoneFinder