Timeservice
The timeservice service can be used to retrieve the current time in one or more places. Additionally, information about time zones and related changes and the time of sunrise and sunset can be queried.
This service can be tested with the Query Builder.
Request Parameters:
| Name | Description | Required |
|---|---|---|
| placeid | Specify the ID of the location you would like to get the current time from. To retrieve the time for multiple places, the corresponding IDs can either be specified as a comma separated list, or by supplying the parameter multiple times (or any combination). There is a limit of maximum 25 locations per requests. Note: It is also possible to specify coordinates or IATA/ICAO codes for airports, see the documentation for the type Location Id for detailed information. Type: Condition: either the | Conditional |
| query | Query for a location by specifying the name. Type: Condition: either the | Conditional |
| qlimit | Maximum number of query results to be returned. This number may be further limited by access key specific restrictions. Type: Accepted values: 0–200 | No |
| geo | Return longitude and latitude for the Type: Accepted values: Default value: | 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 |
| radius | Search radius for translating coordinates (parameter Type: Default value: infinite (but only locations within the same country and time zone are considered) | No |
| sun | Controls if the Type: Accepted values: Default value: | No |
| time | Adds current time under the Type: Accepted values: Default value: | No |
| timechanges | Add a list of time changes during the year to the Type: Accepted values: Default value: | No |
| tz | Add time zone information under the Type: Accepted values: Default value: | No |
| verbosetime | Adds verbose time specification to all ISO 8601 time stamps. Type: Accepted values: Default value: | No |
See also the section “General Parameters”.
Response Elements:
| Name | Description |
|---|---|
| location (XML), locations (JSON) | This element contains the response data. For the XML format, it will be repeated multiple times, while for JSON, it is modeled as an array of objects with the same content. Type: |
Example JSON Request:
https://api.xmltime.com/timeservice?placeid=187&version=3&out=json&prettyprint=1&accesskey={KEY}&expires={TIMESTAMP}&signature={SIGNATURE} Example JSON response:
{
"version": 3,
"billing": {
"credits": 1
},
"locations": [{
"id": "187",
"geo": {
"name": "Oslo",
"country": {
"id": "no",
"name": "Norway"
},
"latitude": 59.913,
"longitude": 10.740
},
"time": {
"iso": "2019-11-01T12:00:28+01:00",
"datetime": {
"year": 2019,
"month": 11,
"day": 1,
"hour": 12,
"minute": 0,
"second": 28
},
"timezone": {
"offset": "+01:00",
"zoneabb": "CET",
"zonename": "Central European Time",
"zoneoffset": 3600,
"zonedst": 0,
"zonetotaloffset": 3600
}
},
"timechanges": [{
"newdst": 3600,
"newzone": null,
"newoffset": 7200,
"utctime": "2019-03-31T01:00:00",
"oldlocaltime": "2019-03-31T02:00:00",
"newlocaltime": "2019-03-31T03:00:00",
"verbose": {
"utctime": {
"datetime": {
"year": 2019,
"month": 3,
"day": 31,
"hour": 1,
"minute": 0,
"second": 0
}
},
"oldlocaltime": {
"datetime": {
"year": 2019,
"month": 3,
"day": 31,
"hour": 2,
"minute": 0,
"second": 0
}
},
"newlocaltime": {
"datetime": {
"year": 2019,
"month": 3,
"day": 31,
"hour": 3,
"minute": 0,
"second": 0
}
}
}
},{
"newdst": 0,
"newzone": null,
"newoffset": 3600,
"utctime": "2019-10-27T01:00:00",
"oldlocaltime": "2019-10-27T03:00:00",
"newlocaltime": "2019-10-27T02:00:00",
"verbose": {
"utctime": {
"datetime": {
"year": 2019,
"month": 10,
"day": 27,
"hour": 1,
"minute": 0,
"second": 0
}
},
"oldlocaltime": {
"datetime": {
"year": 2019,
"month": 10,
"day": 27,
"hour": 3,
"minute": 0,
"second": 0
}
},
"newlocaltime": {
"datetime": {
"year": 2019,
"month": 10,
"day": 27,
"hour": 2,
"minute": 0,
"second": 0
}
}
}
}],
"astronomy": {
"objects": [{
"name": "sun",
"events": [{
"type": "rise",
"hour": 7,
"minute": 37
},{
"type": "set",
"hour": 16,
"minute": 22
}]
}]
},
"matchparam": "187"
}]
}
Example XML Request:
https://api.xmltime.com/timeservice?placeid=187&version=3&out=xml&prettyprint=1&accesskey={KEY}&expires={TIMESTAMP}&signature={SIGNATURE} Example XML response
<?xml version="1.0" encoding="UTF-8"?>
<data version="3">
<billing>
<credits>1</credits>
</billing>
<location id="187" matchparam="187">
<geo>
<name>Oslo</name>
<country id="no">Norway</country>
<latitude>59.913</latitude>
<longitude>10.740</longitude>
</geo>
<time iso="2019-11-01T12:01:36+01:00">
<datetime>
<year>2019</year>
<month>11</month>
<day>1</day>
<hour>12</hour>
<minute>01</minute>
<second>36</second>
</datetime>
<timezone offset="+01:00">
<zoneabb>CET</zoneabb>
<zonename>Central European Time</zonename>
<zoneoffset>3600</zoneoffset>
<zonedst>0</zonedst>
<zonetotaloffset>3600</zonetotaloffset>
</timezone>
</time>
<timechanges>
<change newdst="3600" newzone="" newoffset="7200" utctime="2019-03-31T01:00:00" oldlocaltime="2019-03-31T02:00:00" newlocaltime="2019-03-31T03:00:00">
<utctime>
<datetime>
<year>2019</year>
<month>3</month>
<day>31</day>
<hour>01</hour>
<minute>00</minute>
<second>00</second>
</datetime>
</utctime>
<oldlocaltime>
<datetime>
<year>2019</year>
<month>3</month>
<day>31</day>
<hour>02</hour>
<minute>00</minute>
<second>00</second>
</datetime>
</oldlocaltime>
<newlocaltime>
<datetime>
<year>2019</year>
<month>3</month>
<day>31</day>
<hour>03</hour>
<minute>00</minute>
<second>00</second>
</datetime>
</newlocaltime>
</change>
<change newdst="0" newzone="" newoffset="3600" utctime="2019-10-27T01:00:00" oldlocaltime="2019-10-27T03:00:00" newlocaltime="2019-10-27T02:00:00">
<utctime>
<datetime>
<year>2019</year>
<month>10</month>
<day>27</day>
<hour>01</hour>
<minute>00</minute>
<second>00</second>
</datetime>
</utctime>
<oldlocaltime>
<datetime>
<year>2019</year>
<month>10</month>
<day>27</day>
<hour>03</hour>
<minute>00</minute>
<second>00</second>
</datetime>
</oldlocaltime>
<newlocaltime>
<datetime>
<year>2019</year>
<month>10</month>
<day>27</day>
<hour>02</hour>
<minute>00</minute>
<second>00</second>
</datetime>
</newlocaltime>
</change>
</timechanges>
<astronomy>
<object name="sun">
<event type="rise" hour="07" minute="37"/>
<event type="set" hour="16" minute="22"/>
</object>
</astronomy>
</location>
</data>