Dstlist
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:
| Name | Description | Required |
|---|---|---|
| year | The year you want to retrieve the information for. Type: 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 Type: 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 contact us. Type: Default value: 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: Accepted values: Default value: | No |
| onlydst | Return only countries which actually observe DST in the queried year. Other countries will be suppressed. Type: Accepted values: Default value: | No |
| timechanges | Add a list of time changes during the year to the Type: Accepted values: Default value: | 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: Accepted values: Default value: | No |
| template | Specify the name of a template if you want the result rendered in a specific format (e.g. CSV). Type: Accepted values: 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: Accepted values: Default value: | No |
See also the section “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
dstlistservice 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 includingcsvstyle=2in the request.
Response Elements
| Name | Description |
|---|---|
| dstlist | The DST information for each country or region. Type: |
Example JSON Request:
https://api.xmltime.com/dstlist?country=ie&year=2011&listplaces=1&version=3&out=json&prettyprint=1&accesskey={KEY}&expires={TIMESTAMP}&signature={SIGNATURE} Example JSON response:
{
"version": 3,
"billing": {
"credits": 1
},
"dstlist": [{
"region": {
"country": {
"id": "ie",
"name": "Ireland"
},
"desc": "All locations",
"biggestplace": "Dublin",
"locations": [{
"id": "78",
"name": "Dublin"
},{
"id": "1964",
"name": "Limerick"
},{
"id": "1999",
"name": "Galway"
},{
"id": "2093",
"name": "Cork"
},{
"id": "2206",
"name": "Waterford"
},{
"id": "2207",
"name": "Dundalk"
},{
"id": "3500",
"name": "Letterkenny"
},{
"id": "4411",
"name": "Drogheda"
},{
"id": "4412",
"name": "Navan"
},{
"id": "4413",
"name": "Kilkenny"
},{
"id": "4414",
"name": "Sligo"
},{
"id": "4415",
"name": "Longford"
},{
"id": "4416",
"name": "Tullamore"
},{
"id": "4417",
"name": "Carlow"
},{
"id": "4714",
"name": "Skibbereen"
},{
"id": "4942",
"name": "Carrickmacross"
},{
"id": "5234",
"name": "Tralee"
},{
"id": "5284",
"name": "Westport"
},{
"id": "5299",
"name": "Belmullet"
},{
"id": "5365",
"name": "Mullingar"
},{
"id": "5411",
"name": "Waterville"
},{
"id": "5494",
"name": "Port Laoise"
},{
"id": "5541",
"name": "Ennis"
},{
"id": "5595",
"name": "Wexford"
}]
},
"stdtimezone": {
"zoneabb": "GMT",
"offset": "+00:00",
"zonename": "Greenwich Mean Time",
"zoneoffset": 0,
"zonedst": 0,
"zonetotaloffset": 0
},
"dsttimezone": {
"zoneabb": "IST",
"offset": "+01:00",
"zonename": "Irish Standard Time",
"zoneoffset": 0,
"zonedst": 3600,
"zonetotaloffset": 3600
},
"dststart": "2011-03-27",
"dstend": "2011-10-30"
}]
}
Example XML Request:
https://api.xmltime.com/dstlist?country=ie&year=2011&listplaces=1&version=3&out=xml&prettyprint=1&accesskey={KEY}&expires={TIMESTAMP}&signature={SIGNATURE} Example XML response
<data version="3">
<billing>
<credits>1</credits>
</billing>
<dstlist>
<dstentry>
<region>
<country id="ie">Ireland</country>
<desc>All locations</desc>
<biggestplace>Dublin</biggestplace>
<locations>
<location id="78" name="Dublin"/>
<location id="1964" name="Limerick"/>
<location id="1999" name="Galway"/>
<location id="2093" name="Cork"/>
<location id="2206" name="Waterford"/>
<location id="2207" name="Dundalk"/>
<location id="3500" name="Letterkenny"/>
<location id="4411" name="Drogheda"/>
<location id="4412" name="Navan"/>
<location id="4413" name="Kilkenny"/>
<location id="4414" name="Sligo"/>
<location id="4415" name="Longford"/>
<location id="4416" name="Tullamore"/>
<location id="4417" name="Carlow"/>
<location id="4714" name="Skibbereen"/>
<location id="4942" name="Carrickmacross"/>
<location id="5234" name="Tralee"/>
<location id="5284" name="Westport"/>
<location id="5299" name="Belmullet"/>
<location id="5365" name="Mullingar"/>
<location id="5411" name="Waterville"/>
<location id="5494" name="Port Laoise"/>
<location id="5541" name="Ennis"/>
<location id="5595" name="Wexford"/>
</locations>
</region>
<stdtimezone offset="+00:00">
<zoneabb>GMT</zoneabb>
<zonename>Greenwich Mean Time</zonename>
<zoneoffset>0</zoneoffset>
<zonedst>0</zonedst>
<zonetotaloffset>0</zonetotaloffset>
</stdtimezone>
<dsttimezone offset="+01:00">
<zoneabb>IST</zoneabb>
<zonename>Irish Standard Time</zonename>
<zoneoffset>0</zoneoffset>
<zonedst>3600</zonedst>
<zonetotaloffset>3600</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=3&out=text&template=csv&accesskey={KEY}&expires={TIMESTAMP}&signature={SIGNATURE} Example XML 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,