timezone 0.4.3

  • README.md
  • Installing
  • Versions
  • 43


This package provides time zone database and time zone aware DateTime object.

Current Time Zone database version: 2015b


TimeZone objects require time zone data, so the first step is to load one of our time zone databases.

We are providing two different APIs for browsers and standalone environments.

Initialization for browser environment

Import package:timezone/browser.dart library and run async function Future initializeTimeZone([String path]).

import 'package:timezone/browser.dart';

initializeTimeZone().then((_) {
  final detroit = getLocation('America/Detroit');
  final now = new TZDateTime.now(detroit);

Initialization for standalone environment

Import package:timezone/standalone.dart library and run async function Future initializeTimeZone([String path]).

import 'package:timezone/standalone.dart';

initializeTimeZone().then((_) {
  final detroit = getLocation('America/Detroit');
  final now = new TZDateTime.now(detroit);

Local Location

By default, when library is initialized, local location will be UTC.

To overwrite local location you can use setLocalLocation(Location location) function.

initializeTimeZone().then((_) {
  final detroit = getLocation('America/Detroit');



Each location in the database represents a national region where all clocks keeping local time have agreed since 1970. Locations are identified by continent or ocean and then by the name of the location, which is typically the largest city within the region. For example, America/New_York represents most of the US eastern time zone; America/Phoenix represents most of Arizona, which uses mountain time without daylight saving time (DST); America/Detroit represents most of Michigan, which uses eastern time but with different DST rules in 1975; and other entries represent smaller regions like Starke County, Indiana, which switched from central to eastern time in 1991 and switched back in 2006.

The tz database

Get location by Olsen timezone ID

final detroit = getLocation('America/Detroit');

We don't provide any functions to get locations by timezone abbreviations because of the ambiguities.

Alphabetic time zone abbreviations should not be used as unique identifiers for UTC offsets as they are ambiguous in practice. For example, "EST" denotes 5 hours behind UTC in English-speaking North America, but it denotes 10 or 11 hours ahead of UTC in Australia; and French-speaking North Americans prefer "HNE" to "EST".

The tz database


TimeZone object represents time zone and contains offset, dst flag, and name in the abbreviated form.

final timeInUtc = new DateTime.utc(1995, 1, 1);
final timeZone = detroit.timeZone(timeInUtc.millisecondsSinceEpoch);

TimeZone aware DateTime

TZDateTime object implements standard DateTime interface and contains information about location and time zone.

final date = new TZDateTime(detroit, 2014, 11, 17);

Converting DateTimes between Time Zones

To convert between time zones, just create a new TZDateTime object using from constructor and pass Location and DateTime to the constructor.

final localTime = new DateTime(2010, 1, 1);
final detroitTime = new TZDateTime.from(time, detroit);

This constructor supports any objects that implements DateTime interface, so you can pass native DateTime object or ours TZDateTime.

<a name="databases"></a> Time Zone databases

We are using IANA Time Zone Database to build our databases.

We are currently building three different database variants:

  • default (doesn't contain deprecated and historical zones with some exceptions like US/Eastern). 308kb/72kb gzip
  • all (contains all data from the IANA Time Zone Database). 370kb/100kb gzip
  • 2010-2020 (default database that contains historical data from 2010 until 2020). 71kb/16kb gzip

Updating Time Zone databases

Script for updating Time Zone database, it will automatically download the IANA Time Zone Database and compile into our native format.

$ pub run tool/get -s 2014h

Argument -s is for specifying source version.


  • Fix Dart 1.14 incompatibility further.


  • Bad pub publish. Ignore.


  • Fix Dart 1.14 incompatibility with packageRoot returning null.


  • Remove usage of tuple package.
  • Upgrade unittest package to test.
  • Fix database URL for "latest" database.
  • Add tool/dartfmt for formatting source.


  • generate_data_subset script is removed. It will be available as a separate package.


  • TimeZone database updated to 2015b.
  • Removed local location detection heuristics (didn't worked properly). Local location is initialized with UTC location by default, use setLocalLocation to change local location.
  • TimeZone database format is changed, data is aligned.


  • Fixed bug with String formatting (invalid offsets for minutes).


  • Fixed bug with Calendar-type constructor.


  • Added initializeTimeZoneSync function for standalone environments.
  • Fixed bug with script path on Windows.


  • TimeZone database updated to "2014j".
  • "args" and "path" moved from dev dependencies to dependencies.


  • tzfile library renamed to tzdata.
  • Added zone1970.tab parser to tzdata library.
  • Removed package:collection dependency.

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:

  timezone: ^0.4.3

2. Install it

You can install packages from the command line:

with pub:

$ pub get

Alternatively, your editor might support pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:

import 'package:timezone/timezone.dart';
Version Uploaded Documentation Archive
0.4.3 Feb 23, 2016 Go to the documentation of timezone 0.4.3 Download timezone 0.4.3 archive
0.4.2 Feb 23, 2016 Go to the documentation of timezone 0.4.2 Download timezone 0.4.2 archive
0.4.1 Jan 30, 2016 Go to the documentation of timezone 0.4.1 Download timezone 0.4.1 archive
0.4.0 Nov 24, 2015 Go to the documentation of timezone 0.4.0 Download timezone 0.4.0 archive
0.3.1 Apr 26, 2015 Go to the documentation of timezone 0.3.1 Download timezone 0.3.1 archive
0.3.0 Apr 8, 2015 Go to the documentation of timezone 0.3.0 Download timezone 0.3.0 archive
0.2.5 Jan 6, 2015 Go to the documentation of timezone 0.2.5 Download timezone 0.2.5 archive
0.2.4 Dec 25, 2014 Go to the documentation of timezone 0.2.4 Download timezone 0.2.4 archive
0.2.3 Dec 15, 2014 Go to the documentation of timezone 0.2.3 Download timezone 0.2.3 archive
0.2.2+2 Dec 15, 2014 Go to the documentation of timezone 0.2.2+2 Download timezone 0.2.2+2 archive

All 23 versions...

Describes how popular the package is relative to other packages. [more]
Code health derived from static analysis. [more]
Reflects how tidy and up-to-date the package is. [more]
Weighted score of the above. [more]
Learn more about scoring.

We analyzed this package on Oct 10, 2018, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.0.0
  • pana: 0.12.4


Detected platforms: unsure

Low code quality prevents platform classification.

Health issues and suggestions

Fix lib/src/date_time.dart. (-68.36 points)

Analysis of lib/src/date_time.dart failed with 4 errors:

line 11 col 7: Missing concrete implementations of getter 'DateTime.microsecond' and getter 'DateTime.microsecondsSinceEpoch'.

line 321 col 3: Invalid override. The type of 'TZDateTime.difference' ('(TZDateTime) → Duration') isn't a subtype of 'DateTime.difference' ('(DateTime) → Duration').

line 386 col 3: Invalid override. The type of 'TZDateTime.isAtSameMomentAs' ('(TZDateTime) → bool') isn't a subtype of 'DateTime.isAtSameMomentAs' ('(DateTime) → bool').

line 396 col 3: Invalid override. The type of 'TZDateTime.compareTo' ('(TZDateTime) → int') isn't a subtype of 'DateTime.compareTo' ('(DateTime) → int').

Fix lib/src/tzdb.dart. (-58.02 points)

Analysis of lib/src/tzdb.dart failed with 3 errors, 1 hint:

line 77 col 29: Undefined name 'ASCII'.

line 170 col 7: Undefined name 'ASCII'.

line 183 col 20: Undefined name 'ASCII'.

line 9 col 8: Unused import: 'dart:convert'.

Fix lib/src/tzdata/zicfile.dart. (-44.59 points)

Analysis of lib/src/tzdata/zicfile.dart failed with 2 errors, 3 hints:

line 71 col 14: Undefined name 'ASCII'.

line 74 col 10: Undefined name 'ASCII'.

line 8 col 8: Unused import: 'dart:convert'.

line 161 col 15: The value of the local variable 'lastTransitionOffset' isn't used.

line 270 col 15: The value of the local variable 'lastTransitionOffset' isn't used.

Fix additional 7 files with analysis or formatting issues. (-26.38 points)

Additional issues in the following files:

  • lib/src/location.dart (1 error, 1 hint)
  • lib/standalone.dart (2 hints)
  • lib/browser.dart (Run dartfmt to format lib/browser.dart.)
  • lib/src/env.dart (Run dartfmt to format lib/src/env.dart.)
  • lib/src/location_database.dart (Run dartfmt to format lib/src/location_database.dart.)
  • lib/src/tools.dart (Run dartfmt to format lib/src/tools.dart.)
  • lib/src/tzdata/zone_tab.dart (Run dartfmt to format lib/src/tzdata/zone_tab.dart.)

Maintenance issues and suggestions

Fix platform conflicts. (-20 points)

Low code quality prevents platform classification.

Package is too old. (-100 points)

The package was released more than two years ago.

The description is too short. (-20 points)

Add more detail about the package, what it does and what is its target use case. Try to write at least 60 characters.

Maintain an example. (-10 points)

Create a short demo in the example/ directory to show how to use this package. Common file name patterns include: main.dart, example.dart or you could also use timezone.dart.


Package Constraint Resolved Available
Direct dependencies
Dart SDK >=1.9.0
path ^1.3.0 1.6.2
Dev dependencies
args any
browser any
glob any
logging any
test ^0.12.0