`converttime` – Convert Time Between Time Zones

Home > API > Documentation > Version 2 > converttime – Convert Time Between Time Zones

The converttime service can be used to convert any time from UTC or any of the supported locations to any other of the supported locations.

You have to specify a time stamp either in ISO8601 representation via the iso parameter, or you have to specify the individual components of the time stamp. Skipped components will not yield an error message, but use a default value instead (which corresponds to 01.01.2001, 00:00:00).

This service can be tested with the Query Builder.

Request Parameters.

Name	Description	Required
fromid	Specify the ID of the location for which the supplied time stamp corresponds. If the time stamp is in UTC, use the location id `1440` (or `/utc`). Type: String/Location Id	Yes
toid	Specify the ID of the location(s) for which the time stamp should be converted. You can supply multiple locations by either providing them as comma separated list, or by repeating the parameter multiple times. Type: String/Location Id	No
iso	Time stamp in ISO8601 format. Type: String/ISO8601 Timestamp Example: 2011-06-08T09:18:16 Condition: either the `iso` or the parameters for the separate field time stamp have to be specified.	Conditional
year	Year component of the time stamp. Type: Integer Condition: either the `iso` or the parameters for the separate field time stamp have to be specified.	Conditional
month	Month component of the time stamp. Type: Integer Condition: either the `iso` or the parameters for the separate field time stamp have to be specified.	Conditional
day	Day component of the time stamp. Type: Integer Condition: either the `iso` or the parameters for the separate field time stamp have to be specified.	Conditional
hour	Hour component of the time stamp. Type: Integer Condition: either the `iso` or the parameters for the separate field time stamp have to be specified.	Conditional
min	Minute component of the time stamp. Type: Integer Condition: either the `iso` or the parameters for the separate field time stamp have to be specified.	Conditional
sec	Seconds component of the time stamp. Type: Integer Condition: either the `iso` or the parameters for the separate field time stamp have to be specified.	Conditional
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 (parameters `fromid` and `toid`) 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
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: `0`	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

Response Elements.

Name	Description
utc	UTC time stamp of requested time. Type: UtcType
location (XML), locations (JSON)	This element contains the time information for the locations in the request. 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

Name

Description

utc

UTC time stamp of requested time.

Type: UtcType

location (XML), locations (JSON)

This element contains the time information for the locations in the request. 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/converttime?fromid=750&toid=146&iso=2011-12-31T00:00:00;version=2&out=json&prettyprint=1&accesskey={KEY}&expires={TIMESTAMP}&signature={SIGNATURE}

Example JSON response

{
  "version": 1,
  "utc": {
    "time": {
      "iso": "2011-12-30T13:00:00",
      "datetime": {
        "year": 2011,
        "month": 12,
        "day": 30,
        "hour": 13,
        "minute": 0,
        "second": 0
      }
    }
  },
  "locations": [{
    "id": 750,
    "matches": "source",
    "geo": {
      "name": "Lord Howe Island",
      "state": "Lord Howe Island",
      "country": {
        "id": "au",
        "name": "Australia"
      }
    },
    "time": {
      "iso": "2011-12-31T00:00:00+11:00",
      "datetime": {
        "year": 2011,
        "month": 12,
        "day": 31,
        "hour": 0,
        "minute": 0,
        "second": 0
      },
      "timezone": {
        "offset": "+11:00",
        "zoneabb": "LHDT",
        "zonename": "Lord Howe Daylight Time",
        "zoneoffset": 37800,
        "zonedst": 1800,
        "zonetotaloffset": 39600
      }
    }
  },{
    "id": 146,
    "geo": {
      "name": "Maputo",
      "country": {
        "id": "mz",
        "name": "Mozambique"
      }
    },
    "time": {
      "iso": "2011-12-30T15:00:00+02:00",
      "datetime": {
        "year": 2011,
        "month": 12,
        "day": 30,
        "hour": 15,
        "minute": 0,
        "second": 0
      },
      "timezone": {
        "offset": "+02:00",
        "zoneabb": "CAT",
        "zonename": "Central Africa Time",
        "zoneoffset": 7200,
        "zonedst": 0,
        "zonetotaloffset": 7200
      }
    }
  }]
}

Example XML Request.

https://api.xmltime.com/converttime?fromid=750&toid=146&iso=2011-12-31T00:00:00;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">
  <utc>
    <time iso="2011-12-30T13:00:00">
      <datetime>
        <year>2011</year>
        <month>12</month>
        <day>30</day>
        <hour>13</hour>
        <minute>00</minute>
        <second>00</second>
      </datetime>
    </time>
  </utc>
  <location id="750" matches="source">
    <geo>
      <name>Lord Howe Island</name>
      <state>Lord Howe Island</state>
      <country id="au">Australia</country>
    </geo>
    <time iso="2011-12-31T00:00:00+11:00">
      <datetime>
        <year>2011</year>
        <month>12</month>
        <day>31</day>
        <hour>00</hour>
        <minute>00</minute>
        <second>00</second>
      </datetime>
      <timezone offset="+11:00">
        <zoneabb>LHDT</zoneabb>
        <zonename>Lord Howe Daylight Time</zonename>
        <zoneoffset>37800</zoneoffset>
        <zonedst>1800</zonedst>
        <zonetotaloffset>39600</zonetotaloffset>
      </timezone>
    </time>
  </location>
  <location id="146">
    <geo>
      <name>Maputo</name>
      <country id="mz">Mozambique</country>
    </geo>
    <time iso="2011-12-30T15:00:00+02:00">
      <datetime>
        <year>2011</year>
        <month>12</month>
        <day>30</day>
        <hour>15</hour>
        <minute>00</minute>
        <second>00</second>
      </datetime>
      <timezone offset="+02:00">
        <zoneabb>CAT</zoneabb>
        <zonename>Central Africa Time</zonename>
        <zoneoffset>7200</zoneoffset>
        <zonedst>0</zonedst>
        <zonetotaloffset>7200</zonetotaloffset>
      </timezone>
    </time>
  </location>
</data>

< prev top | next >

All data supplied by

converttime – Convert Time Between Time Zones

Note

`converttime` – Convert Time Between Time Zones