timeservice – Retrieve Current Time for Place

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. 

NameDescriptionRequired
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).

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: String/Location Id

Condition: either the placeid or the query parameter have to be specified.

Conditional
query

Query for a location by specifying the name.

Type: String

Condition: either the placeid or the query parameter have to be specified.

Conditional
qlimit

Maximum number of query results to be returned. This number may be further limited by access key specific restrictions.

Type: Integer

Accepted values: 0–200

No
geo

Return longitude and latitude for the geo object.

Type: Boolean

Accepted values: 0 or 1

Default value: 1

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
radius

Search radius for translating coordinates (parameter placeid) to locations. Coordinates that could not be translated will yield results for the actual geographical position.

Type: Integer

Default value: infinite (but only locations within the same country and time zone are considered)

No
sun

Controls if the astronomy element with information about sunrise and sunset shall be added to the result.

Type: Boolean

Accepted values: 0 or 1

Default value: 1

No
time

Adds current time under the location object.

Type: Boolean

Accepted values: 0 or 1

Default value: 1

No
timechanges

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

Type: Boolean

Accepted values: 0 or 1

Default value: 1

No
tz

Add time zone information under the time object.

Type: Boolean

Accepted values: 0 or 1

Default value: 1

No
verbosetime

Adds verbose time specification to all ISO 8601 time stamps.

Type: Boolean

Accepted values: 0 or 1

Default value: 1

No

See also the section called “General Parameters”.

Response Elements. 

NameDescription
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: Array of LocationType

Example JSON Request. 

https://api.xmltime.com/timeservice?placeid=187&version=2&out=json&prettyprint=1&accesskey={KEY}&expires={TIMESTAMP}&signature={SIGNATURE}

Example JSON response

{
  "version": 1,
  "locations": [{
    "id": 187,
    "geo": {
      "name": "Oslo",
      "country": {
        "id": "no",
        "name": "Norway"
      },
      "latitude": 59.913,
      "longitude": 10.740
    },
    "time": {
      "iso": "2011-11-09T09:00:51+01:00",
      "datetime": {
        "year": 2011,
        "month": 11,
        "day": 9,
        "hour": 9,
        "minute": 0,
        "second": 51
      },
      "timezone": {
        "offset": "+01:00",
        "zoneabb": "CET",
        "zonename": "Central European Time",
        "zoneoffset": 3600,
        "zonedst": 0,
        "zonetotaloffset": 3600
      }
    },
    "timechanges": [{
      "newdst": 3600,
      "newzone": null,
      "newoffset": 7200,
      "utctime": "2011-03-27T01:00:00",
      "oldlocaltime": "2011-03-27T02:00:00",
      "newlocaltime": "2011-03-27T03:00:00",
      "verbose": {
        "utctime": {
          "datetime": {
            "year": 2011,
            "month": 3,
            "day": 27,
            "hour": 1,
            "minute": 0,
            "second": 0
          }
        },
        "oldlocaltime": {
          "datetime": {
            "year": 2011,
            "month": 3,
            "day": 27,
            "hour": 2,
            "minute": 0,
            "second": 0
          }
        },
        "newlocaltime": {
          "datetime": {
            "year": 2011,
            "month": 3,
            "day": 27,
            "hour": 3,
            "minute": 0,
            "second": 0
          }
        }
      }
    },{
      "newdst": 0,
      "newzone": null,
      "newoffset": 3600,
      "utctime": "2011-10-30T01:00:00",
      "oldlocaltime": "2011-10-30T03:00:00",
      "newlocaltime": "2011-10-30T02:00:00",
      "verbose": {
        "utctime": {
          "datetime": {
            "year": 2011,
            "month": 10,
            "day": 30,
            "hour": 1,
            "minute": 0,
            "second": 0
          }
        },
        "oldlocaltime": {
          "datetime": {
            "year": 2011,
            "month": 10,
            "day": 30,
            "hour": 3,
            "minute": 0,
            "second": 0
          }
        },
        "newlocaltime": {
          "datetime": {
            "year": 2011,
            "month": 10,
            "day": 30,
            "hour": 2,
            "minute": 0,
            "second": 0
          }
        }
      }
    }],
    "astronomy": {
      "objects": [{
        "name": "sun",
        "events": [{
          "type": "rise",
          "hour": 7,
          "minute": 58
        },{
          "type": "set",
          "hour": 16,
          "minute": 3
        }]
      }]
    }
  }]
}

Example XML Request. 

https://api.xmltime.com/timeservice?placeid=187&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">
  <location id="187">
    <geo>
      <name>Oslo</name>
      <country id="no">Norway</country>
      <latitude>59.913</latitude>
      <longitude>10.740</longitude>
    </geo>
    <time iso="2011-11-09T09:01:26+01:00">
      <datetime>
        <year>2011</year>
        <month>11</month>
        <day>9</day>
        <hour>09</hour>
        <minute>01</minute>
        <second>26</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="2011-03-27T01:00:00" oldlocaltime="2011-03-27T02:00:00" newlocaltime="2011-03-27T03:00:00">
        <utctime>
          <datetime>
            <year>2011</year>
            <month>3</month>
            <day>27</day>
            <hour>01</hour>
            <minute>00</minute>
            <second>00</second>
          </datetime>
        </utctime>
        <oldlocaltime>
          <datetime>
            <year>2011</year>
            <month>3</month>
            <day>27</day>
            <hour>02</hour>
            <minute>00</minute>
            <second>00</second>
          </datetime>
        </oldlocaltime>
        <newlocaltime>
          <datetime>
            <year>2011</year>
            <month>3</month>
            <day>27</day>
            <hour>03</hour>
            <minute>00</minute>
            <second>00</second>
          </datetime>
        </newlocaltime>
      </change>
      <change newdst="0" newzone="" newoffset="3600" utctime="2011-10-30T01:00:00" oldlocaltime="2011-10-30T03:00:00" newlocaltime="2011-10-30T02:00:00">
        <utctime>
          <datetime>
            <year>2011</year>
            <month>10</month>
            <day>30</day>
            <hour>01</hour>
            <minute>00</minute>
            <second>00</second>
          </datetime>
        </utctime>
        <oldlocaltime>
          <datetime>
            <year>2011</year>
            <month>10</month>
            <day>30</day>
            <hour>03</hour>
            <minute>00</minute>
            <second>00</second>
          </datetime>
        </oldlocaltime>
        <newlocaltime>
          <datetime>
            <year>2011</year>
            <month>10</month>
            <day>30</day>
            <hour>02</hour>
            <minute>00</minute>
            <second>00</second>
          </datetime>
        </newlocaltime>
      </change>
    </timechanges>
    <astronomy>
      <object name="sun">
        <event type="rise" hour="07" minute="58"/>
        <event type="set" hour="16" minute="03"/>
      </object>
    </astronomy>
  </location>
</data>

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