Understand TimeZone

All time series evaluation APIs accept a parameter for timezone, which indicates the desired time zone for the data. The engine identifies the source time zone of the data, converts them to the desired zone and performs time series math on this transformed data.

Supported time zone choices include:

• NONE,
• UTC,
• A timezone identifier,
• A timezone offset.

Copy link to this section

None

Creating a datetime in NONE timezone represents that the datetime is in "logical time" that is there is no zone information associated with this datetime and means the date and time are as stated by this object. For example, "2010-01-01T04:00:00" without any zone information means 4 am on the 1st of January, 2010. It doesn't matter whether this date is being viewed in California or Australia. It will still remain the 1st of January, 2010 4am. This is the default mode for all time series computation.

Metric Evaluation in various time zones
Organization.evalMetric({
 expression:"ElectricityConsumption",
 id:"MyOrgId",
 start:"2016-01-01"
 end:"2017-01-01"
 interval:"HOUR",
 timeZone: "NONE"
});
//Expected results should be in logical times (no zone) and will always have 24 hours in a day when evaluated at intervals finer or equal to an HOUR

Copy link to this section

UTC

Coordinated Universal Time (UTC) is the basis for civil time today. This 24-hour time standard is kept using highly precise atomic clocks combined with the Earth's rotation (Reference: UTC: The World's Time Standard)

Organization.evalMetric({
 expression:"ElectricityConsumption",
 id:"MyOrgId",
 start:"2016-01-01"
 end:"2017-01-01"
 interval:"HOUR",
 timeZone: "UTC"
});
//Expected results will be in UTC time zone and will always have 24 hours in a day when evaluated at intervals finer or equal to an HOUR

Copy link to this section

Timezone identifier

Create datetime in the specific time zone identified. For example, "2010-01-01T00:00:00-08:00" (America/Los_Angeles). This datetime will follow the day light savings shifts (may not always have 24 hours in a day) and is in the America/Los_Angeles time zone. "-07:00" happens to be the offset for the "America/Los_Angeles" time zone on the 1st of January, 2010.

Organization.evalMetric({
expression:"ElectricityConsumption",
id:"MyOrgId",
start:"2016-01-01"
end:"2017-01-01"
interval:"HOUR",
timeZone: "America/Los_Angeles"
});
//Expected results will be in America/Los_Angeles time zone and could have fewer/more than 24 hours when evaluated at intervals finer or equal to an HOUR

Copy link to this section

Timezone offset

One can create dates in specific offsets. These aren't really time zones but offset from the UTC time. For example, "2010-01-01T00:00:00-08:00", the offset will always be 8 hours shifted from the UTC time. The 24 hour time standard is maintained for offset based date times.

Organization.evalMetric({
 expression:"ElectricityConsumption",
 id:"MyOrgId",
 start:"2016-01-01"
 end:"2017-01-01"
 interval:"HOUR",
 timeZone: "+08:00"
})
//Expected results will be in +08:00 offset and will always have 24 hours in a day when evaluated at intervals finer or equal to an HOUR

Checkout the TimeZone to learn more about generic time zone handling.