TimeZoneFinder

Documentation for TimeZoneFinder.

API

TimeZoneFinder.timezones_at — Function
timezones_at(latitude, longitude)

Get the timezones used at the given latitude and longitude.

If no timezones are known, then an empty list will be returned. Conversely, if the co-ordinates land in a disputed region, all applicable timezones will be returned.

julia> timezones_at(52.5061, 13.358)
1-element Vector{Dates.TimeZone}:
 Europe/Berlin (UTC+1/UTC+2)

julia> timezones_at(69.8, -141)
2-element Vector{Dates.TimeZone}:
 America/Anchorage (UTC-9/UTC-8)
 America/Dawson (UTC-7)
Note

The library will use a version of the timezone-boundary-builder data that is compatible with the version of tzdata currently used by TimeZones.

Nominally this will be the same version as is used by TimeZones, but in some cases an older version might be used.

There are two possible reasons for this:

1. There were no boundary changes in a tzdata release, which means that there will
    never be a boundary release for this particular version.
2. The boundary dataset is not yet available for a new tzdata release.
source
TimeZoneFinder.timezone_at — Function
timezone_at(latitude, longitude)

Get any uniquely applicable timezone at the given latitude and longitude.

julia> timezone_at(52.5061, 13.358)
Europe/Berlin (UTC+1/UTC+2)

See additional note on docstring for timezone_at regarding the version of tzdata that will be used.

Returns

  • a TimeZone instance if latitude and longitude correspond to a unqiue timezone.
  • nothing if no timezone is found.

An exception is raised if multiple timezones correspond to this location - use timezones_at to obtain all the matches.

source

Implementation details

Artifact

This module is based upon OpenStreetMap data, which has been compiled into shape files by timezone-boundary-builder. We define an Artifact for each release (since 2021c) of these raw JSON shape files.

When a new upstream release is made, a new artifact will be created by a package maintainer. Refer to the artifact_build directory for a helper script.

Parsed cache

This raw data is provided in JSON format, so the first time a package uses it, it is parsed (which can take tens of seconds). Subsequently, a serialized binary version in a scratch space is loaded, which is much faster. This cache is re-used so long as the package and Julia versions remain the same. After an upgrade the cache will be re-generated, which can cause a one-off latency of a few tens of seconds.

Parsed format

The parsed data contains multiple (about 1000) polygons, each with a correpsonding time-zone. Each polygon is stored as a PolyArea along with its axis-aligned bounding box. This bounding box is used to speed up checks for containment.

Lookup

Given a (latitude, longitude) point, we perform a linear scan over all polygons. For each polygon we check for containment, using the bounding box to quickly dismiss polygons that are far away.

Note

In the future, performance might be improved further by building a more fine-grained spatial index.