Dates and Times

Date Formats

We support the ISO 8601 format for passing in dates and times. This allows for a very flexible array of options, allowing you to pass in the level of detail you need to.

The full representation of a date and time is of the format:

yyyy-MM-ddTHH:mm:ss.SSSZ

Defaulting

We recommend using the full date, time and time zone where possible. However, for convenience, we default to the earliest possible value when a field is not specified. For example, if you do not specify a time of day, we will default to 00:00 (midnight).

If the time zone is not specified, we default the time zone according to the context of the call. For calculations and savings analyses, dates in the request without a time zone will default to the time zone of the tariff used in the calculation. This is referred to as the Tariff Time Zone. In cases where there is no appropriate tariff context for the call, the time zone will default to UTC, that is, an offset of 00:00.

This table illustrates some example valid dates and times, and their equivalent for the general case where the timezone is defaulted to UTC:

This table illustrates some example valid dates and times, and their equivalent, where we can default to the Tariff Time Zone. In this example, the calculation is for a tariff in US Pacific time zone, so the Tariff Time Zone will be Pacific Daylight Time, -07:00 for dates in summer, and Pacific Standard Time, -08:00, for dates in winter.

To validate if a format you are using is supported, you can use the Echo validation method. For http request parameters, be sure to http encode the input, in particular if you’re using a UTC+ time zone offset. The + will need to be encoded into %2B. Read more about the ISO 8601 format here.

Date Ranges

We represent date ranges with a fromDateTime and a toDateTime. The fromDateTime is inclusive, and the toDateTime is exclusive; that is to say that the date range includes the instant of the fromDateTime and does not include the instant of the toDateTime. This extends also to dates. A Tariff with an effectiveDate of 2015-01-01 and an endDate of 2015-04-01 is effective on January 1st and March 31st but is no longer effective on April 1st.

We refer to this way of representing date ranges as “Genability-style” (it matches the “start/end” way that ISO 8601 represents time intervals). Some utilities represent date ranges (such as for billing periods) differently. This difference is captured in the BillingPeriodRepresentation object.

Time Zones in Responses

When running a calculation or making a price request, the dates and times in the response will always be in the tariff’s time zone. On the request you can specify dates and times with a different time zone and these will be used in the Price and Calculate requests; however, the response will be in the tariff’s time zone. Most tariffs are available in only one time zone. However, there are still some tariffs which are offered in more than one time zone. For these, a UTC time zone will be returned.

Date Periods

We also support passing in dates as periods of time. This can be useful for passing in usage data when running calculations, and in this case these are added as an attribute of the TariffInput being passed in. Date periods are a string that defines the “notation” for the period. This leverages common notation used for defining, parsing and formatting dates and times.

We are expanding the support for date periods and, at the moment, the following syntax is supported:

• e - day of the week, from 1 (Mon) to 7 (Sun)
• H - hour of the day, from 0 to 23
• periods of either 1:5 (weekdays) and 6:7 (weekends)

Here are some examples:

• For weekdays at 10 a.m.: { period: "1:5e 10H" }
• For weekends at 2 p.m.: { period: "6:7e 14H" }
• For hourly periods:

1
2
3
4
5
6
7
8
9
10
11
12
13
{ period: "1:5e 1H", other fields ... }
{ period: "1:5e 2H", other fields ... }
{ period: "1:5e 3H", other fields ... }
{ period: "1:5e 4H", other fields ... }
{ period: "1:5e 5H", other fields ... }
...
{ period: "1:5e 22H", other fields ... }
{ period: "1:5e 23H", other fields ... }
{ period: "6:7e 1H", other fields ... }
{ period: "6:7e 2H", other fields ... }
...
{ period: "6:7e 22H", other fields ... }
{ period: "6:7e 23H", other fields ... }

Usage Profile Data (Clipping and Grouping)

When working with usage profile reading data, there are additional optional parameters groupBy and clipBy for controlling the behavior of boundary readings. These control whether to include the inner readings which are completely contained in the requested intervals, or to include the outer readings which contain the requested intervals but extend beyond these intervals.

More details on these controls can be found on the Profile documentation in the Get a Usage Profile section.