TzWorld

Resolve timezones from a location using data from the timezone-boundary-builder project.

Installation

Add tz_world to your list of dependencies in mix.exs:

def deps do
  [
    {:tz_world, "~> 0.2.0"}
  ]
end

After adding TzWorld as a dependency, run mix deps.get to install it. Then run mix tz_world.update to install the timezone data.

NOTE No data is installed with the package and until the data is installed with mix tz_world.update all calls to TzWorld.timezone_at/1 will return {:error, :noent}.

Installing the Timezones Geo JSON data

Installing tz_world from source or from hex does not include the timezones geo JSON data. The data is requried and to install or update it run:

mix tz_world.update

This task will download, transform, zip and store the timezones geo data. Depending on internet and computer speed this may take a few minutes.

Data location

By default the data will be placed in ./priv/tz_world.

An alternative location can be configured in config.exs as follows:

config :tz_world,
  data_dir: "some/directory"

Updating the Timezone data

From time-to-time the timezones geo JSON data is updated in the upstream project. The mix task mix tz_world.update will update the data if it is available. This task can be run at any time, it will detect when new data is available and only download it when a new release is available. The generated file TIMEZONES_GEOJSON_VERSION is used to track the current installed version of the data.

A running application can also be instructed to reload the data by executing TzWorld.reload_timezone_data.

Usage

The primary API is TzWorld.timezone_at. It takes either a Geo.Point struct or a longitude and latitude in degrees. Note the parameter order: longitude, latitude.

iex> TzWorld.timezone_at(%Geo.Point{coordinates: {3.2, 45.32}})
{:ok, "Europe/Paris"}

iex> TzWorld.timezone_at(3.2, 45.32)
{:ok, "Europe/Paris"}

iex> TzWorld.timezone_at(%Geo.PointZ{coordinates: {-74.006, 40.7128, 0.0}})
{:ok, "America/New_York"}

iex> TzWorld.timezone_at(%Geo.Point{coordinates: {1.3, 65.62}})
{:error, :time_zone_not_found}