TimeZone Database
The TimeZone Database provides time zone information for a given location (latitude and longitude). It's simple: you give latitude and longitude and the Database returns the unix (Olson) time zone ID (e.g., "America/Chicago", "Europe/London"), the Windows Standard Name for the time zone (e.g., "Pacific Standard Time", "Central European Standard Time"), and the offset from UTC, either for the current time or for the date and time specified in the optional dateTime parameter in the query string.
Unlike some other tools for accomplishing this task, Ask Geo look-ups are based on an actual map of the world, rather than the "closest point of interest". This ensures accuracy and that you actually get a result for all locations. And unlike some other tools, we return an actual time zone ID rather than just an offset. The API and underlying library is quite fast (see the Performance Section below).
The Ask Geo Time Zone Database takes full account of Daylight Saving Time.
Time Zone Map
The map below was generated from the TimeZone Database.
The colors are selected to reflect the offset from GMT and the outlines show the boundaries and shorelines of the land-based time zones of the world. The vertical stripes in the open ocean are the natural time zones implied solely by the longitude. Time zones that don't observe Daylight Savings Time (DST) are colored the same as their corresponding natural time zone; those that do are colored slightly darker but with the same hue. Time zones that do not use an offset from UTC that is an integer number of hours have a color that is a proportional mixture of the colors of the bracketing natural time zones (e.g., Iran and India).
Time Zone Database Updates
In order to provide the local time offset from UTC for a given latitude and longitude, the Ask Geo Time Zone Database relies on two data sets:
- Map Data
- We utilize a polygonal map of the world's time zones to map from a given latitude and longitude to a time zone ID. Because of the way in which these time zone IDs were defined, this map data does not change very often, and most of the changes are not substantial. Keep in mind that changes to the daylight saving time rules for a given country do not require updating the map data that define the time zone IDs. We no longer provide updates to this data, so while it does change infrequently, pre-existing errors and the rare changes that do occur will not be updated.
- ZoneInfo
- We use the Olson "zoneinfo" time zone database, which gives the local time offset from UTC for a given time zone ID and at a given moment in time. This data is updated fairly regularly, such as when a country changes its daylight saving time rules. We keep things up-to-date on this, but because we always return the time zone ID as well as any local time offset from UTC, you can always query your own local copy of the zoneinfo database if you are keen to have control over this update process. See the section below on ZoneInfo udpates for more information on this topic.
Map Data Updates
At its core, Ask Geo's Time Zone Database is the Map Data that converts from latitude and longitude to a time zone ID. There are lots of ways to go from a time zone ID to a local time offset from UTC, but there are only a couple options for this geographical query, and we believe Ask Geo to be the best in the market. We keep this data up-to-date and seemlessly make it available to our Web API customers.
Updates for Java and .NET Library Customers
The Ask Geo Java and .NET Time Zone Libaries require our proprietary Map Data file to function. Library customers may download the latest version of the Map Data file by going to their Account Page and scrolling down to the "Download Data Files" section. Map Data files are versioned to avoid confusion about what version you are currently using.
Furthermore, whenever we make a substantial revision to the Map Data file, we notify our existing customers of the update so that they know to upgrade it in their systems.
ZoneInfo Updates
The Ask Geo Time Zone Database uses the Olson time zone database (often referred to as just the "tz database" or "zoneinfo database") to provide a local time offset from UTC for a given time zone ID and at a given time. The zoneinfo database is maintained by the IANA (Internet Assigned Numbers Authority), and international web standards organization. The official home page for the project is at http://www.iana.org/time-zones. That page contains download links to the latest versions of the database. You may also read about the project on its wikipedia page.
The zoneinfo database consists of a number of time zone IDs, each of which has a set up rules for computing what the local time is in that time zone at any time since 1970. Each country in the world has its own time zone ID, even if it has had the same local time as another country since 1970. Time zone IDs are named for an important city in the time zone, since cities tend to change name less often than countries do. For example, U.S. Central Time is called "America/Chicago" and that same ID is used for both Standard Time and Daylight Saving Time. This is possible because each ID can have any number of rules to determine what the local time offset was from UTC at any time since 1970. For this reason, Arizona, which doesn't observe Daylight Saving Time has its own time zone, "America/Phoenix", even though its time matches neighboring states during some parts of the year.
The zoneinfo database is part of the Linux and Macintosh operating systems, and is used to power Java's TimeZone class. It is also included in many other programming languages and there is even a library to let you use it in Microsoft's .NET framework (see comments on Noda Time below). Regular updates to the database are made and posted on its home page and there is a mailing list that you can sign up for on that page to be notified when changes are published. Since this is a built-in part of a lot of operating systems and programming languages, you really just need to keep your OS and programming framework up to date in order to have the latest version of the zoneinfo database.
Updates for Java Library Customers
For customers interested in the Ask Geo Time Zone Java Library, you have a couple options for keeping your zoneinfo database up-to-date:
- The simplest is to use the internal Java TimeZone class and be sure to keep your JVM updated. Oracle is responsible for incorporating changes in the zoneinfo database and those are included in regular JVM updates. Just keep you JVM udpated and you should be all set.
- You can also consider using Joda Time an open-source third-party replacement for Java's built-in date, time, and time zone classes. Joda Time has a number of advantages over the built-in Java implementations and we recommend taking a look at it to see if you prefer it to the built-in classes. One caveat to keep in mind is that Joda Time does not regularly update when changes are made to the zoneinfo database. You have to perform these updates yourself, following the instructions listed here.
Updates for .NET Library Customers
For customers interested in the Ask Geo Time Zone .NET Library, you have two main options available to you:
- We provide a mapping from Olson (zoneinfo) time zone IDs to Windows Standard Names for time zones. You can use that mapping to get the Windows Standard Name for a given time zone and then use the built-in time zone machinery in .NET to get the local time offset from UTC. This has the advantage of drawing on Microsofts time zone database, which is automatically updated whenever you update Windows. The disadvantage of this option is that the mapping from Olson time zone ID to Windows Standard Name is not an officially supported list by either the zoneinfo group or the Microsoft team, so errors might creep in over time as the two databases evolve. We do our best to keep this mapping up-to-date but we can't guarantee its accuracy.
- We strongly recommend using Noda Time instead. This is a .NET port of the Joda Time library mentioned above and will allow you to use the zoneinfo database directly. This allows you to avoid using the mapping from time zone ID to Windows Standard Name, which is the most error-prone part of the system.
Database Statistics
The TimeZone Database contains 398 distinct time zone IDs, made up of 27,732 polygonal shapes and defined by a total of 2,106,509 vertexes. The smallest time zone is "Europe/Vatican" with a total area of only 0.6 square kilometers. The largest time zone is "Asia/Kolkata" with a total area of 3,160,581 square kilometers. The median time zone (by area) is "Asia/Sakhalin" with a total area of 74,594 square kilometers. Please note that the total number of time zones in the time zone database is larger than the 398 time zones described by this Database because the time zone database contains a number of obsolete and redundant time zones.
Map Accuracy
The data file that Ask Geo uses to define the time zone shapes is derived from a number of publicly available vector maps, including VMAP0. As such, they are based on the WGS-84 horizontal datum. These maps do not always agree with the boundaries shown on Google Maps. We cannot say with certainty, but we assume that Google Maps is more accurate at displaying the political boundaries. Under that assumption it is possible to assess the error of Ask Geo in the vicinity of borders.
We have done a casual manual sampling of a few different borders and it appears as though the error is on the order of a couple of hundred feet, which is quite small.
International Waters
The rules for time zones in the ocean and other bodies of water that are not fully contained within one country are specified by a UN convention. The UN convention states that outside of territorial waters the timezone reverts to the natural time zone, with an integer hour offset determined by dividing the longitude by 15 degrees and rounding down.
Following the UN convention is not, in our opinion, the best thing to do. Territorial waters only extend 14 miles from the coast. But there are many coastlines that do not fall within the natural time-zone, and even those that do during standard time (such as California) typically do not during daylight savings time. So if a fishing boat or coastal cruise ship (e.g., in transit from Los Angeles to San Francisco) passes further than 14 miles away from the California coast during daylight savings time, the UN convention suggests they should change all their clocks until they are back within range of shore. We don't have personal experience with deep sea fishing boats or cruise ships, but we're willing to bet that this is not what they actually do.
We designed the system to do what we consider to be the sensible thing, and to be consistent with existing graphical representations of the world's time zones. For example, most time zone maps we've seen give islands a fairly wide berth. We decided to do the same.
So our system assigns a time zone according to the following rules:
-
If the query point is within the land boundaries of a time zone region, we assign it that ID.
-
Else if the query point is withing 200 km from the nearest time zone region, we assign it to that ID.
-
Else we assign it to the natural time zone.
We selected the snap-to distance to be 200 km in order to produce a map that matched other time zone maps that we've seen and so that several large seas and inland lakes (e.g., the Mediterranean, the Caspian, the Great Lakes, and the Black Sea) snapped to the nearest land-defined time zone, rather than reverting to the natural time zone.
Returned Values
The TimeZone Database returns several parameters in response to a given query point. While all these parameters are returned with a single call to the Web API, for performance reasons the Java and .NET Libraries divides them into three separate groups.
The first group is common to all the Databases and pertains to the query point's relationship to the map region from which the returned values were drawn.
| Key | Description | Units | Type |
|---|---|---|---|
| AskGeoId | The internally-used AskGeo unique ID for the returned polygon | n/a | int |
| IsInside | Whether or not the query point is inside the returned polygon | n/a | boolean |
| MinDistanceKm | The distance from the query point to the nearest interior point of the returned polygon | kilometers | float |
The second group contains only the Olson time zone ID, the most important response from this Database.
| Key | Description | Units | Type |
|---|---|---|---|
| TimeZoneId | Olson time zone ID | n/a | String |
The third group consists of several supplemental return parameters that are added to the Olson time zone ID in the Web API response.These are parameters that are easily obtained in Java and .NET but might be difficult to obtain when accessing the Web API from a different language.
| Key | Description | Units | Type |
|---|---|---|---|
| InDstNow | Whether or not the time zone is currently in Daylight Savings Time (DST) | n/a | boolean |
| CurrentOffsetMs | The current offset between UTC and local time in milliseconds | milliseconds | float |
| ShortName | The conventional three-letter time zone abbreviation (e.g., EST, CST, MST, PST) | n/a | String |
| WindowsStandardName | The time zone ID used in Windows | n/a | String |
Please note that if the optional dateTime parameter is specified in the query string of the API call, that date and time are used in place of the current date and time for all results given in the response to that query.
Java Library
All Ask Geo Java Libraries are compatible with Java 6, have no external dependencies, and are thread safe. Each Database comes with an associated Data File that must provided at constructor time to populate the internal data structures.
The libraries come in both double and single (float) precision versions, with the former consuming just under twice the resident memory of the latter. For reference, the single precision version is accurate to about 2.4 meters, which is more than sufficient for most applications.
If you are interested in purchasing this Library or gaining access to the Web API, please see the:
Java Documentation
There are only two classes that you need to be aware of to use the Ask Geo TimeZone Java Library.
- class TimeZoneMap
-
Contains map data and allows queries on the Database.
- class TimeZoneResult
-
Embodies the result of a query on a TimeZoneMap instance.
They are described in further detail in the sections that follow.
The method signatures listed in this section are for the single precision (float) version of the library. For the double precision version, just replace float with double.
Please note that the documentation below is intended to provide you with an easy-to-understand presentation of the essentials of how to use the Ask Geo TimeZone Java Library.
For full documentation of the classes included, please see the:
TimeZoneMap
The TimeZoneMap class stores the map data and exposes a query method to find a time zone ID from a given latitude and longitude. Because each TimeZoneMap instance is quite large, we recommend instantiating a single static instance in your project. The methods that you will need to use are as follows.
class TimeZoneMap {
static TimeZoneMap create(InputStream dataFileStream)
- InputStream dataFileStream: Input Stream of the Data File to be read to create this map
TimeZoneResult findResult(float latDeg, float lonDeg)
- float latDeg: Latitude of the query point (degrees)
- float lonDeg: Longitude of the query point (degrees)
// Additional methods exist in this class; for complete documentation, please see the Full Java Docs
}
TimeZoneResult
The TimeZoneResult class embodies the result of a query on a TimeZoneMap instance. All of the results listed in the Returned Values Section may be accessed using an accessor whose method name consists of "get" followed by the "Key" parameter from the Returned Values tables. Those tables also specify the type of the returned value. For example, the most important accessor is:
class TimeZoneResult {
String getTimeZoneId()
// Additional methods exist in this class; for complete documentation, please see the Full Java Docs
}
Java Example
The following is a complete example program demonstrating the use of the Ask Geo TimeZone Java Library.
import com.askgeo.flt.timezone.TimeZoneMap;
import com.askgeo.flt.timezone.TimeZoneResult;
import java.io.FileInputStream;
import java.util.TimeZone;
public class TimeZoneExample {
static float[][] examplePoints = {{37f, -122f}, {42f, -89f}, {52f, -1f}, {51f, -31f}};
static String license = "INSERT YOUR LICENSE STRING HERE";
static String dataFilePath = "askgeo-time-zone-1.1.1.dat";
public static void main(String[] args) {
try {
TimeZoneMap map = TimeZoneMap.create(new FileInputStream(dataFilePath));
map.authorize(license);
for (float[] point : examplePoints) {
TimeZoneResult result = map.findResult(point[0], point[1]);
String tzId = result.getTimeZoneId();
TimeZone tz = TimeZone.getTimeZone(tzId);
int offsetMs = tz.getOffset(System.currentTimeMillis());
System.out.println(" Latitude: " + point[0] +
", Longitude: " + point[1] +
", Time Zone ID: " + tzId +
", Current Offset: " + offsetMs + " ms");
}
} catch (Exception e) {
e.printStackTrace();
}
}
}
Java Library Performance and Memory Consumption
Ask Geo was designed from the ground up to be high performance. Our custom spatial index delivers blazing-fast response times. Furthermore, we've designed the Ask Geo Java Libraries to be thread safe and to not utilize synchronized methods or statements in the performance-critical query code. This means that computers with multiple processors or cores can take full advantage of those cores to deliver even faster performance.
We tested the performance of the Library using a single thread on a computer with an Intel Core i7 3.33 GHz running 64-bit Windows 7. For each version of the library, we tested:
- Construction Time
-
The time it took to construct an instance of the TimeZone Database object.
- Per-Query Time
-
The average response time for a single query. This was measured by running 100,000 queries, randomly distributed over the full extent of the map.
- Memory
-
Resident memory of a TimeZone Database instance, as estimated by measuring the JVM's used memory after running the GC when running a simple test application containing only the map. This will lead to a slight over-estimate of the resident memory because it will include the overhead of the test application.
- Data File Size
-
The file size of the Data File associated with this Database.
| Precision | Construction Time | Per-Query Time | Memory | Data File Size |
|---|---|---|---|---|
| Single | 2.27 seconds | 5.14e-04 seconds | 32.4 MB | 40.2 MB |
| Double | 1.88 seconds | 5.91e-04 seconds | 58.9 MB | 40.2 MB |
.NET Library
All Ask Geo .NET Libraries are compatible with .NET 4 and are thread safe. Each Database comes with an associated Data File that must provided at constructor time to populate the internal data structures. Except for a few small changes to be more consistent with .NET style and coding conventions, the Ask Geo .NET Libraries are a direct port of the AskGeo Java Libraries.
Where relevant both double and single (float) precision versions of the various classes are provided, with the former consuming just under twice the resident memory of the latter. For reference, the single precision version is accurate to about 2.4 meters, which is more than sufficient for most applications.
If you are interested in purchasing this Library or gaining access to the Web API, please see the:
.NET Documentation
There are only two classes that you need to be aware of to use the Ask Geo TimeZone .NET Library.
- class TimeZoneMap
-
Contains map data and allows queries on the Database.
- class TimeZoneResult
-
Embodies the result of a query on a TimeZoneMap instance.
They are described in further detail in the sections that follow.
The method signatures listed in this section are for the single precision (float) version of the library. For the double precision version, just replace float with double.
Please note that the documentation below is intended to provide you with an easy-to-understand presentation of the essentials of how to use the Ask Geo TimeZone .NET Library.
For full documentation of the classes included, please see the:
TimeZoneMap
The TimeZoneMap class stores the map data and exposes a query method to find a time zone ID from a given latitude and longitude. Because each TimeZoneMap instance is quite large, we recommend instantiating a single static instance in your project. The methods that you will need to use are as follows.
class TimeZoneMap {
static TimeZoneMap Create(Stream dataFileStream)
- Stream dataFileStream: Input Stream of the Data File to be read to create this map
TimeZoneResult FindResult(float latDeg, float lonDeg)
- float latDeg: Latitude of the query point (degrees)
- float lonDeg: Longitude of the query point (degrees)
// Additional methods exist in this class; for complete documentation, please see the Full .NET Docs
}
TimeZoneResult
The TimeZoneResult class embodies the result of a query on a TimeZoneMap instance. All of the results listed in the Returned Values Section may be accessed using an accessor whose method name consists of "Get" followed by the "Key" parameter from the Returned Values tables. Those tables also specify the type of the returned value. For example, the most important accessor is:
class TimeZoneResult {
String GetWindowsStandardName()
// Additional methods exist in this class; for complete documentation, please see the Full .NET Docs
}
Example
The following is a complete example program demonstrating the use of the Ask Geo TimeZone .NET Library.
using System;
using System.IO;
using AskGeo.Flt;
class TimeZone {
static void Main(string[] args) {
float[,] examplePoints = {{37f, -122f}, {42f, -89f}, {52f, -1f}, {51f, -31f}};
String license = "INSERT YOUR LICENSE STRING HERE";
String dataFilePath = @"askgeo-time-zone-1.1.1.dat";
TimeZoneMap map = TimeZoneMap.Create(new FileStream(dataFilePath, FileMode.Open));
map.Authorize(license);
for (int i = 0; i < examplePoints.GetLength(0); i++ ) {
TimeZoneResult result = map.FindResult(examplePoints[i, 0], examplePoints[i, 1]);
String standardName = result.GetWindowsStandardName();
TimeZoneInfo tzInfo = TimeZoneInfo.FindSystemTimeZoneById(standardName);
TimeSpan offset = tzInfo.GetUtcOffset(DateTime.Now);
Console.WriteLine(" Latitude: " + examplePoints[i, 0] +
", Longitude: " + examplePoints[i, 1] +
", Time Zone Name: " + standardName +
", Current Offset: " + offset.TotalMilliseconds + " ms");
}
}
}
.NET Library Performance and Memory Consumption
Ask Geo was designed from the ground up to be high performance. Our custom spatial index delivers blazing-fast response times. Furthermore, we've designed the Ask Geo .NET Libraries to be thread safe and to not utilize synchronized methods or statements in the performance-critical query code. This means that computers with multiple processors or cores can take full advantage of those cores to deliver even faster performance.
The Ask Geo Libraries were originally designed and written in Java and ported to .NET. Consequently, detailed performance and memory consumption information is available for the Java Libraries but not for the .NET Libraries. We have run spot checks on a few of our test cases and found that the .NET Libraries have essentially the same performance characteristics as the Java Libraries. This is unsurprising given the similarities between the languages and the virtual machines on which they run. See the Java Performance Section for detailed information on construction time, per-query time, and memory consumption.
