Time

The Time API provides an alternative to NTP and other time services to get the current time. In the general case, we recommend using services and protocols especially designed for time-related operations, such as NTP as opposed to the Time API. When resources such as memory local time-keeping hardware are limited or unavailable, you may find it useful to call our Time API to obtain the current time and perform local time-keeping from then on.

Please keep in mind that the time returned by the Time API is the time of our servers at the moment the request is processed. It does not take the round-trip time into account.

API Status
General Availability:
https://api.evrythng.io/v2/time

Jump To ↓

TimeInfoDocument Data Model
Read the current time
Read timezone time

TimeInfoDocument Data Model

.timestamp (integer, read-only)
    Number of milliseconds since the Epoch.

.localTime (string, read-only)
    The date, time and zone offset specified as per ISO 8601.

.nextChange (integer, read-only)
    when the next change in offset is expected.

.offset (integer, read-only)
    The current offset in milliseconds of the timezone compared 
    to UTC.

{
  "type": "object",
  "description": "Object describing the current time, with timezone info.",
  "properties": {
    "timestamp": {
      "type": "integer",
      "description": "Number of milliseconds since the Epoch.",
      "minimum": 1508749759486,
      "readOnly": true
    },
    "localTime": {
      "type": "string",
      "description": "The date, time and zone offset specified as per ISO 8601.",
      "readOnly": true
    },
    "nextChange": {
      "type": "integer",
      "description": "when the next change in offset is expected.",
      "readOnly": true
    },
    "offset": {
      "type": "integer",
      "description": "The current offset in milliseconds of the timezone compared to UTC.",
      "minimum": 0,
      "readOnly": true
    }
  }
}

{
  "localTime": "2017-11-17T12:12:00.696Z",
  "nextChange": 1521939600000,
  "offset": 0,
  "timestamp": 1510920720696
}

Query Parameters

?tz - String
The time zone to retrieve the local time for, as per TZDB.

The nextChange field can be used when the client is unable to compute the local time correctly. Instead of querying the Time API periodically, this field can be used by the client to know when it's relevant to query the Time API again.

Note that time zones like GMT+1 don't know anything about daylight saving time (DST). Usually, these are the cities that move from one time zone to another at specific times in the year. Hence if you want to track DST with the time API, use a city time zone, such as "Europe/Zurich" as opposed to "Etc/GMT+1".

Note that a Timestamp is by definition always in UTC, thus the timestamp field is not affected by the tz parameter. This means that nextChange is in UTC as well.

Read the current time

Read the current server time.

GET /time

curl -X GET 'http://time.evrythng.com/time'

evrythng.api({ url: '/time' }).then(console.log);

HTTP/1.1 200 OK
Accept: application/json

{
  "timestamp": 1428571989696
}

Read timezone time

Read the time for a specified timezone.

GET /time?tz=Europe%2FZurich

curl -X GET 'http://time.evrythng.com/time?tz=Europe%2FZurich'

HTTP/1.1 200 OK
Accept: application/json

{
  "timestamp" : 1428576687786,
  "offset" : 7200000,
  "localTime" : "2015-04-09T12:51:27.786+02:00",
  "nextChange" : 1445734800000
}