TZFinder 1.0.15

TZFinder

Get IANA time zone id from geo location.

API documentation

Features

• Based on data from the Timezone Boundary Builder.
• Includes three compressed data files with different resolutions, selectable in the .csproj
• Custom data files with any resolution can be created easily with a dotnet tool. Etc/GMT time zones can also be included (otherwise they are calculated at runtime).
• Supports disputed areas with two time zones.
• The entire area of a time zone can be traversed, e.g. for graphical display.
• Trim safe and AOT compatible.

Getting started

Install the TZFinder package.

dotnet package add TZFinder

Simple retrieval of the IANA id at a position

string id = TZFinder.TZLookup.GetTimeZoneId(2.255419f, 47.479083f); // Europe/Paris

Optionally, you can select a different data file in the .csproj (default: Medium)

  <PropertyGroup>
    <TimeZoneData>Large</TimeZoneData>
  </PropertyGroup>

MSBuild properties

If the TZFinder NuGet package is referenced by an application (directly or transitively), the desired data file is automatically included as Content in the project so that it can be used at runtime. The file can also be included as an EmbeddedResource, which is the simplest method for Blazor WASM applications, for example.

At runtime, the file is searched for by default as a file or assembly resource with the name TZFinder.TimeZoneData.bin. In all other cases, a path to the data file can be set with TZLookup.TimeZoneDataPath or an open readable stream can be set with TZLookup.TimeZoneDataStream.

Data files

TZFinder is based on the GeoHash algorithm, in which the Earth's surface is alternately halved longitudinally and laterally. Each halving is counted as 1 level. Every 5 levels correspond to one GeoHash character. In this way, bounding boxes are generated up to a maximum level that lie within the boundaries of a time zone (maxLevel).

The raw data for the boundaries comes from the Timezone Boundary Builder. To simplify the calculation, all points from the boundaries that are too close to each other are removed (minRingDistance).

Included data files

Creating your own data file

Install the tool in your project or as global tool and run it with dotnet tz-build.

dotnet new tool-manifest
dotnet tool install TZFinder.Builder
dotnet tz-build 

The calculation of high-resolution data files is very computationally intensive and can take a long time. Please note that the calculation will utilize the CPU at 100%.

All downloaded and generated files are cached in the %LocalAppData%\TZFinder directory. If you encounter any issues, you can delete the entire directory.

To use a custom data file, set TimeZoneData to None and include the created file in your project.

  <PropertyGroup>
    <TimeZoneData>None</TimeZoneData>
  </PropertyGroup>

  <ItemGroup>
    <Content Include="TZFinder.TimeZoneData.bin" 
             CopyToOutputDirectory="Always" 
             SkipUnchangedFilesOnCopyAlways="true" />

    

    <EmbeddedResource Include="TZFinder.TimeZoneData.bin"
                      LogicalName="TZFinder.TimeZoneData.bin" />
  </ItemGroup>

Platforms

TZFinder is compatible with .NET (Core) 2.0 or higher and .NET Framework 4.7.2 or higher and has been tested with all project types that generate .exe assemblies (Console, ASP.NET Core, WinForms, WPF, WinUI 3, UWP Native, Modern UWP).

Blazor WASM

Add this to use TZFinder from a WebAssembly

  <PropertyGroup>
    <TimeZoneItem>EmbeddedResource</TimeZoneItem>
  </PropertyGroup>

MAUI

The data file is automatically included as MauiAsset. Run this code before using TZLookup.

  TZFinder.TZLookup.TimeZoneDataStream = await FileSystem.OpenAppPackageFileAsync(TZFinder.TZLookup.DataFileName);

Android

The data file is automatically included as AndroidAsset. Run this code before using TZLookup.

  TZFinder.TZLookup.TimeZoneDataStream = Assets!.Open(TZFinder.TZLookup.DataFileName, Access.Streaming);

Other Platforms

Please let me know, if you have issues using TZFinder on other platforms.