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. 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). Similarly, not specifying a timezone defaults the timezone to GMT. The full representation is of the format:


This table illustrates some example valid dates and times:

Sample Description
2011 Equivalent to 2011-01-01T00:00:00.000Z
2011-06 Equivalent to 2011-06-01T00:00:00.000Z
2011-06-23 Equivalent to 2011-06-23T00:00:00.000Z
2011-06-23T18 Equivalent to 2011-06-23T18:00:00.000Z
2011-06-23T18:45 Equivalent to 2011-06-23T18:45:00.000Z
2011-06-23T18:45Z Equivalent to 2011-06-23T18:45:00.000Z (GMT timezone)
2011-06-23T18:45-0700 Equivalent to 2011-06-23T18:45:00.000-0700 (US Pacific time zone)

To validate if a format you are using is supported, you can use the Echo validation method. Also, be sure to http encode the input, in particular if you're using a GMT+ 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.


When running a calculation or making a price request, the dates and times in the response will always be in the tariff's timezone. On the request you can specify dates and times with a different timezone and these will be used in the Price and Calculate requests; however, the response will be in the tariff's timezone. Most tariffs are available in only one timezone. However, there are still some tariffs which are offered in more than one timezone (for example, Florida Power & Light). For these, a UTC timezone 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:
{ 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.