World Time Zone Database Documentation

XML File Details

One of the data formats provided with our Time Zone Database service is an XML formatted file. This XML file can be used within your project as the data source without requiring retyping of the information shown in this printed guide.

This XML file contains information about each Location, including pattern-based rules for Daylight Savings Time, where applicable. The fields or nodes used in the XML file to describe each location are:

1  Location ID	Unique Location code, based on ISO 3166-1 list used by the United Nations
2  Country	Name of Country
3  Region	Name of Region (used only if Country has more than one time zone)
4  Landmarks	Contains subnodes for <City>. Most locations have at least one city to provide the best known or most populated city or cities in this specific Region or Country
5  StdName	Full local name for Time Zone when observing Standard Time*
6  StdAbbrev	Local abbreviation for Time Zone when observing Standard Time*
7  DstName	Full local name for Time Zone when observing Daylight Saving Time*
8  DstAbbrev	Local abbreviation for Time Zone when observing Daylight Saving Time*
9  TimeRules	Contains <Rule> subnodes with current and future time rule information for this location. Each Rule contains: a) Effective  Date in UTC when rule should be considered to be in effect b) StdBias  Normal difference of time in this location from UTC, shown in hours and minutes (+/-HHMM) c) DstBias  If location supports Daylight Saving Time, difference in time of this location from UTC during dates DST is in effect, shown in hours and minutes (+/-HHMM) d) DstStart  Rule for when Daylight Saving Time begins in this location, if applicable. If location uses DST and has a pattern which can be determined, this field shows the pattern as 0200 LST-SUN-MAR meaning at 02:00 am local time on the last Sunday in March. e) DstEnd  Rule for when Daylight Saving Time ends in this location, if it has a start. Please note that old rules will be purged from the database after they are no longer effective. Any items with effective dates of January 1, 2010 have been in effect for longer, but have been given this date simply to show they are in effect now, if not superseded by a later rule.

* please note that not all locations around the world have an official time zone name for their location. If a country has only one time zone, they often would not find it necessary to name it at all! There are other sites on the Internet that have made up their own names to fill in these blanks, but they don't necessarily agree with each other and people in that location would not necessarily recognize the names these sites came up with. So, don't be surprised to find blank entries, as we only list time zone names for places that actually have them. If you find a blank for a location you are interested in, we recommend that you simply refer to it with generic terms such as Standard Time or Daylight Savings Time in lieu of a real time zone name.

Click here to view an sample of what the XML file looks like, to show some real examples of how these fields are used.
 

ASCII CSV File Details

One of the data formats provided with our Time Zone Database service is an ASCII delimited file. This ASCII file can be used within your project as the data source without requiring retyping of the information shown in this printed guide.

If you are unfamiliar with what an ASCII comma delimited text file or CSV file looks like, each location is on a separate line, with quotation marks at the beginning and end of each field and with commas separating the fields.

The first line of the CSV file contains the field names to define what data the rest of the file holds. These fields are:

1  Location ID	Unique Location code, based on ISO 3166-1 list used by the United Nations
2  Country	Name of Country
3  Region	Name of Region (used only if Country has more than one time zone)
4  City List	List of some major cities in this specific Region or Country
5  StdBias	Normal difference in hours and minutes of time in this location from UTC (+/-HHMM)
6  DstBias	If location supports Daylight Saving Time, difference in time of this location from UTC during dates DST is in effect, shown in hours and minutes (+/-HHMM)
7  DstStartPattern	Rule for when Daylight Saving Time begins in this location, if applicable. If location uses DST and has a pattern which can be determined, this field shows the pattern as 0200 LST-SUN-MAR meaning at 02:00 am local time on the last Sunday in March.
8  DstEndPattern	Rule for when Daylight Saving Time ends in this location
9  MapFile	Pertains to World Time Server web site only for map display
10  ThisYearDSTStart	In local time, actual day and time Daylight Saving Time begins in the current year
11  ThisYearDSTEnd	In local time, actual day and time this location will return to standard time
12  NextYearDSTStart	In local time, actual day and time Daylight Saving Time begins next year
13  NextYearDSTEnd	In local time, actual day and time this location will return to standard time
14  ThisYearUTCStart	In UTC time, actual day and time Daylight Saving Time begins in the current year
15  ThisYearUTCEnd	In UTC time, actual day and time this location will return to standard time
16  NextYearUTCStart	In UTC time, actual day and time Daylight Saving Time begins next year
17  NextYearUTCEnd	In UTC time, actual day and time this location will return to standard time
18  StdZoneName	Full local name for Time Zone when observing Standard Time*
19  StdZoneAbbrev	Local abbreviation for Time Zone when observing Standard Time*
20  DstZoneName	Full local name for Time Zone when observing Daylight Saving Time*
21  DstZoneAbbrev	Local abbreviation for Time Zone when observing Daylight Saving Time*

 
* please note that not all locations around the world have an official time zone name for their location. If a country has only one time zone, they often would not find it necessary to name it at all! There are other sites on the Internet that have made up their own names to fill in these blanks, but they don't necessarily agree with each other and people in that location would not necessarily recognize the names these sites came up with. So, don't be surprised to find blank entries, as we only list time zone names for places that actually have them. If you find a blank for a location you are interested in, we recommend that you simply refer to it with generic terms such as Standard Time or Daylight Savings Time in lieu of a real time zone name.

By the way, UTC refers to Universal Time Co-ordinated, also known as Greenwich Mean Time (GMT) or Zulu time. Local times around the world can be compared by the difference (or bias) between the each location and UTC. UTC time is not necessarily the time in any given country. For example, the United Kingdom will change its clocks for Summer Time or Daylight Saving Time for part of the year and during that period will be an hour off of UTC!

Click here for a sample of what the ASCII text file will look like.
 

World Time .NET component for Windows and Web projects

If you want to provide accurate local times on your own website or applications, we have included a special .NET component (ChaosSoftware.WorldTime.dll). This will allow you to simply query this object to get local times around the world, rather than creating a time project from scratch.

Requirements

• Microsoft .NET Framework 4.5 or .NET Core 3.1
• ChaosSoftware.WorldTime.dll - a .NET component supplied free to World Time Data Subscribers
• worldtime.xml - one of the data files available with our World Time Data Subscription
• Friendly to both 32bit or 64bit development

Using the WorldTime .NET Component in ASP.NET

The worldtime component can take any time in UTC and a location and return to you the matching time in the specified location. Here is a basic walkthrough of using this component to retrieve and display a current time around the world.

First, you need to add the ChaosSoftware.WorldTime.dll to your project.

Second, before you can use any functions, you need to load the supplied WorldTime data into memory. If you plan to use the time functions often, you should likely put this in your Application Start area. Here is a sample from a Global.asax.vb file :

     Sub Application_Start(ByVal sender As Object, ByVal e As EventArgs)
         ChaosSoftware.WorldTime.LoadData("c:\worldtimedata\worldtime.xml")
     End Sub

With the data loaded you can now find the data for a specific location, then ask for the current local time of the location. Here is a sample:

     Dim ThisLocation As New ChaosSoftware.WorldTime.Location("US-TX")
     Dim ThisLocalTime as ChaosSoftware.WorldTime.TimeResponse
     ThisLocalTime = ThisLocation.GetLocalTime
     Response.Write(ThisLocalTime.ReturnedTime.ToString)

The TimeResponse mentioned in this sample provides two important pieces of information: both a converted local time as of right when the code executed, as well as a Boolean value to indicate whether this location is observing daylight savings time or not at the time given. Providing the knowledge of whether DST is in use or not is why we have our own TimeResponse object instead of just returning a Date alone.

You don't have to only get the current time either. You can feed in any UTC time and have it respond back with a local time. There is also a .GetUTCTime function to do the reverse and change any local time to a matching UTC time. Here is an example of using both functions to convert a time in one location to another:

     Dim Location1 As New ChaosSoftware.WorldTime.Location("US-TX")
     Dim ThisUTCTime as ChaosSoftware.WorldTime.TimeResponse
     ThisUTCTime = Location1.GetUTC(New Date(2012, 12, 31, 23, 59, 00))
     Dim Location2 as New ChaosSoftware.WorldTime.Location("AU-NSW")
     Dim TimeInLocation2 as ChaosSoftware.WorldTime.TimeResponse
     TimeInLocation2 = Location2.GetLocalTime(ThisUTCTime.TimeResponse)
     Response.Write(TimeInLocation2.ReturnedTime.ToString)

  

DLL Documentation

Location Functions

Location
Parameters: LocationID
Returns: ChaosSoftware.WorldTime.Location (as defined below)
Purpose: Provide any Location in the WorldTime database and this function will retrieve all the information for this location in a strongly classed, ready to use object.
Example:

      Dim ThisLocation As New ChaosSoftware.WorldTime.Location("US-TX")

A Location object has the following attributes:

• LocationID As String - the unique identifier for this location
• Country As String
• Region As String - this field is only used if the country has multiple time zones, usually a state or province name or other information to help describe the specific location
• CityList As String - a simple comma delimited list of major cities found in this location
• StdBias As String - the offset from UTC for this location, in +/-HHMM format
• StdBiasInMinutes As Integer - the offset from UTC for this location, in Minutes, as an Integer
• DstBias As String - if empty, location does not use DST. If not empty, the offset from UTC used when DST is in effect, in +/-HHMM format
• DstBiasInMinutes As Integer - the offset from UTC for this location when DST is in effect, in Minutes, as an Integer
• DstStart As String - a pattern describing when DST starts in this location
• DstEnd As String - a pattern describing when DST ends in this location
• StdZoneName As String - the local name for the time zone of this location (which may not be unique worldwide!)
• StdZoneAbbrev As String - the local abbreviation for this time zone
• DstZoneName As String - the local name for the time zone when DST is observed
• DstZoneAbbrev As String - the local abbreviation for this time zone when DST is observed

Once you have created a new location, you can use the following functions:

Response Structures

TimeResponse
Purpose: Used with GetLocalTime or GetUtc
Properties:

• ReturnedTime As Date
• LocationInDst as Boolean

TimeRule
Purpose: Used with GetTimeRule to provide alternative time zone rules on a particular date for a particular location
Properties:

• StdBias As String
• StdBiasInMinutes As Integer
• DstBiasAs String
• DstBiasInMinutes As Integer
• DstStart As String
• DstEnd As String

DstDates
Purpose: Used with GetDstDates to provide actual dates and times for DST transitions for this year and next year
Properties:

• StartPattern As String
• EndPattern As String
• ThisYearStartLocal As Date
• ThisYearStartUTC As Date
• ThisYearEndLocal As Date
• ThisYearEndUTC As Date
• NextYearStartLocal As Date
• NextYearStartUTC As Date
• NextYearEndLocal As Date
• NextYearEndUTC As Date

General Functions

LoadData
Parameters: XMLFileName
Purpose: To load your current worldtime.xml file into memory. You will need to supply a complete path where this file can be located.
Example:

     LoadData("c:\project1\worldtimedata\worldtime.xml")

Decode_Date
Parameters: A DST pattern (as given in the DstStart or DstEnd for a Location), Year (as short number)
Returns: DateTime
Purpose: Converts a pattern into a specific day and time for a given year

IsValidLocationID
Parameters: PlaceToCheck (as String)
Returns: Boolean
Purpose: Determine if a potential location id is a valid current location in the database

FindLocationIDs
Parameters: Field, SearchFor, InstrCompare, MultiHit
Returns: String (comma delimited list of LocationIDs)
Purpose: To locate the specific locations that match search criteria
Values:
  Field (String) = Which attribute of a location to search on. Possible values are

1. LocationID - use "locationid" or "1"
2. Country - use "country" or "2"
3. Region - use "region or "3"
4. City List = use "city" or "4"
5. Standard UTC Variance - use "stdbias" or "5"
6. Daylight UTC Variance - use "dstbias" or "6"
7. Daylight Start date and time (pattern) - use "dststart" or "7"
8. Daylight End date and time (pattern) - use "dstend" or "8"

  SearchFor (String) = Any Text or Number to search for.
  InstrCompare (Boolean, optional) = If false, then performs exact match search. If true, it performs an partial match search.
  MultiHit (Boolean, optional) = If false, then returns only first hit. If true, returns a comma delimited list.

GetCountryList
Parameters: none
Returns: SortedList
Purpose: Returns a SortedList suitable for assigning to a listbox or dropdownlist control with all the location names in the WorldTime Database. The key of each item is a display name for the location and the value is the matching LocationID.

GetCountryListSelectedOnly
Parameters: SelectedList (as String - this should be a string of LocationID's separated by commas, such as "US-NY,US-CA,GB,AU-NSW" )
Returns: SortedList
Purpose: Returns a SortedList suitable for assigning to a listbox or dropdownlist control with all the location names for just the asked-for locations. The key of each item is a display name for the location and the value is the matching LocationID.

GetLocationIDList
Parameters: none
Returns: ArrayList
Purpose: Returns a complete list of just the LocationID values.

GetMajorCitiesList
Parameters: none
Returns: SortedList
Purpose: Returns a SortedList suitable for assigning to a listbox with all of the major cities provided in our database. The key of each item is a display name for the location with City and Country and the value is the matching LocationID.

If you are using our DLL file, you won't need to decode the DST Patterns for yourself. However, if you decide to use the raw XML file directly, you will need to use the DST Patterns provided to determine the actual dates in any year where DST starts and stops.

Most rules are provided as repeating patterns, which assumes that the same pattern could continue to be applied to other years. For example, 0200 LST-SUN-MAR would mean the time change took place at 02:00 am local time on the last Sunday in March of any year in the effective range of the Time Rule. The week indicator might include 1ST, 2ND, 3RD, 4TH or LST, followed by three character day of the week, then a three character month.

However, not all rules have these types of repeating patterns. Some locations have a specific day of the month on which they transition. For example, 0200 30/03 would mean the time change always took place on the 30th day of March at 02:00 am, no matter what day of the week that might end up being on a given year. These rules are always in the format of local time in 24 hour format, then a space, then a two digit day, a "/" and finally a two digit month. You might note that these more literal rules always contain a "/" character to divide the day of the month and the month, where as the normal patterns have "-" characters, which might be a good test to see which type of decoding is neccessary to determine the actual dates.

Updates to your subscription are available both through our web site and through a secured feed. Email notificiations of updates are also sent as a reminder when locations have been updated with new or breaking information.