dstlist – Retrieve Daylight Saving Time Information

The dstlist service can be used to obtain data about time zones for all supported countries in our database. This includes the start and end date of daylight savings time, and UTC offset for the time zones.

The resulting data is aggregated on country and time zone level. By default, only information from countries which actually observe DST is returned without listing the individually affected locations – see the parameters listplaces and onlydst to change this behavior.

This service can be tested with the Query Builder.

Request Parameters. 

NameDescriptionRequired
year

The year you want to retrieve the information for.

Type: Integer

Default value: current year

Note

The service does not restrict the years for which information can be queried. However, for years before 1970, the database does not cover all countries completely (this affects e.g. Australia, Canada and the United States of America).
No
country

Specify the country for which you want to retrieve information for. If unspecified, information for all countries will be returned.

Specifying this parameter automatically sets the parameter onlydst to 0.

Type: String/ISO3166-1-alpha-2 country code

Default value: empty, i.e. all countries

No
lang

The preferred language for the texts. An error will be raised if the language code cannot be recognized. In case the text for a specific event cannot be retrieved in the requested language it will be returned in English instead. This is also the default language.

In case you have specific needs for a certain language/translation, please email api@timeanddate.com.

Type: String/ISO639 Language Code

Default value: en

Note

Due to technical limitations, time zone names cannot be translated at the moment.
No
listplaces

For every time zone/country, list the individual places that belong to each record.

Type: Boolean

Accepted values: 0 or 1

Default value: 1

No
onlydst

Return only countries which actually observe DST in the queried year. Other countries will be suppressed.

Type: Boolean

Accepted values: 0 or 1

Default value: 1, unless country is specified

No
timechanges

Add a list of time changes during the year to the dstentry object. This listing e.g. shows changes caused by daylight savings time.

Type: Boolean

Accepted values: 0 or 1

Default value: 0

No
verbosetime

Adds verbose time specification to all ISO 8601 time stamps.

To limit the result size, this parameter is only honored if a single country is queried – otherwise verbose time stamps are suppressed.

Type: Boolean

Accepted values: 0 or 1

Default value: 0

No
template

Specify the name of a template if you want the result rendered in a specific format (e.g. CSV).

Type: String

Accepted values: csv

Default value: None

No
csvstyle

When returning a CSV template you can set this parameter to choose whether the result should be separated by a comma or a semicolon.

Type: Number

Accepted values: 1 (comma) or 2 (semicolon)

Default value: 1

No

See also the section called “General Parameters”.

Supported Text Templates. 

In addition to retrieving this text templates via our API, you can also try out and download this data from our Data Download page.

csv

To use this template, specify this parameter combination: out=text&template=csv.

These templates are used to convert the data returned from the dstlist service to CSV-format. By default, the result will be formatted in American CSV-format (comma as separator). It is possible to return the CSV in European CSV-format (semicolon as separator) by including csvstyle=2 in the request.

Response Elements. 

NameDescription
dstlist

The DST information for each country or region.

Type: Array of DstEntryType

Example JSON Request. 

https://api.xmltime.com/dstlist?country=al&year=2011&listplaces=1&version=2&out=json&prettyprint=1&accesskey={KEY}&expires={TIMESTAMP}&signature={SIGNATURE}

Example JSON response

{
  "version": 1",
  "dstlist": [{
    "region": {
      "country": {
        "id": "al",
        "name": "Republic of Albania"
      },
      "desc": "All locations",
      "biggestplace": "Tirana",
      "locations": [{
        "id": 284,
        "name": "Tirana"
      }]
    },
    "stdtimezone": {
      "zoneabb": "CET",
      "offset": "+01:00",
      "zonename": "Central European Time",
      "zoneoffset": 3600,
      "zonedst": 0,
      "zonetotaloffset": 3600
    },
    "dsttimezone": {
      "zoneabb": "CEST",
      "offset": "+02:00",
      "zonename": "Central European Summer Time",
      "zoneoffset": 3600,
      "zonedst": 3600,
      "zonetotaloffset": 7200
    },
    "dststart": "2011-03-27",
    "dstend": "2011-10-30"
  }
}

Example XML Request. 

https://api.xmltime.com/dstlist?country=al&year=2011&listplaces=1&version=2&out=xml&prettyprint=1&accesskey={KEY}&expires={TIMESTAMP}&signature={SIGNATURE}

Example XML response

<?xml version="1.0" encoding="UTF-8"?>
<data version="1">
  <dstlist>
    <dstentry>
      <region>
        <country id="al">Republic of Albania</country>
        <desc>All locations</desc>
        <biggestplace>Tirana</biggestplace>
        <locations>
          <location id="284" name="Tirana"/>
        </locations>
      </region>
      <stdtimezone offset="+01:00">
        <zoneabb>CET</zoneabb>
        <zonename>Central European Time</zonename>
        <zoneoffset>3600</zoneoffset>
        <zonedst>0</zonedst>
        <zonetotaloffset>3600</zonetotaloffset>
      </stdtimezone>
      <dsttimezone offset="+02:00">
        <zoneabb>CEST</zoneabb>
        <zonename>Central European Summer Time</zonename>
        <zoneoffset>3600</zoneoffset>
        <zonedst>3600</zonedst>
        <zonetotaloffset>7200</zonetotaloffset>
      </dsttimezone>
      <dststart>2011-03-27</dststart>
      <dstend>2011-10-30</dstend>
    </dstentry>
  </dstlist>
</data>

Example CSV Request. 

https://api.xmltime.com/dstlist?year=2015&listplaces=1&version=2&out=text&template=csv&accesskey={KEY}&expires={TIMESTAMP}&signature={SIGNATURE}

Example CSV response

		
CountryCode,CountryName,Region,BiggestPlace,StdTimezone,StdTimezoneName,StdOffset,StdOffsetSec,DstTimezone,DstTimezoneName,DstOffset,DstOffsetSec,DstStart,DstEnd
al,Albania,All locations,Tirana,CET,Central European Time,+01:00,3600,CEST,Central European Summer Time,+02:00,7200,2015-03-29,2015-10-25
ad,Andorra,All locations,Andorra La Vella,CET,Central European Time,+01:00,3600,CEST,Central European Summer Time,+02:00,7200,2015-03-29,2015-10-25
aq,Antarctica,Some locations,Orcadas,ART,Argentina Time,-03:00,-10800,,,,,no DST,
aq,Antarctica,Some locations,South Pole,NZST,New Zealand Standard Time,+12:00,43200,NZDT,New Zealand Daylight Time,+13:00,46800,2015-09-27,2015-04-05
aq,Antarctica,Some locations,Casey,CAST,Casey Time,+08:00,28800,,,,,no DST,
aq,Antarctica,,Neumayer-Station III,UTC,,+00:00,0,,,,,no DST,
aq,Antarctica,,Troll Station,GMT,Greenwich Mean Time,+00:00,0,CET,Central European Time,+01:00,3600,2015-03-01,2015-11-07
		
	

prev top | next >
Terms & Conditions Copyright © Time and Date AS
All data supplied by timeanddate.com