Dates & Times

Date Formats

We support the ISO 8601 format for dates and times. This format provides flexible options, allowing you to specify the level of detail you need.

The complete representation of a date and time follows this format:

yyyy-MM-ddTHH:mm:ss.SSSZ

Defaulting Behavior

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

When no time zone is specified, we default the time zone based on the context of the call. For calculations and savings analyses, dates in requests without a time zone default to the time zone of the tariff used in the calculation (referred to as the "Tariff Time Zone"). When there's no appropriate tariff context for the call, the time zone defaults to UTC (offset of 00:00).

The following table shows example valid dates and times and their UTC equivalents for the general case:

The next table shows examples where we can default to the Tariff Time Zone. In this example, the calculation uses a tariff in the US Pacific time zone, so the Tariff Time Zone is Pacific Daylight Time (-07:00) for summer dates and Pacific Standard Time (-08:00) for winter dates:

To validate whether your format is supported, use the Echo validation method. For HTTP request parameters, ensure you HTTP encode the input, particularly when using a UTC+ time zone offset. The + symbol must be encoded as %2B. Read more about the ISO 8601 format here.

Date Ranges

We represent date ranges using fromDateTime and toDateTime. The fromDateTime is inclusive, while the toDateTime is exclusive. This means the date range includes the instant of the fromDateTime and excludes the instant of the toDateTime. This principle also applies to dates. A Tariff with an effectiveDate of 2015-01-01 and an endDate of 2015-04-01 is effective on January 1st through March 31st but is no longer effective on April 1st.

We call this method of representing date ranges "Arcadia-style" (it matches the "start/end" approach that ISO 8601 uses for time intervals). Some utilities represent date ranges (such as billing periods) differently. This difference is captured in the BillingPeriodRepresentation object.

Time Zones in Responses

When running an on-demand cost calculation or mass calculation request, the dates and times in the response will always use the tariff's time zone. You can specify dates and times with different time zones in your request, and these will be used in the calculator requests; however, the response will always use the tariff's time zone. Most tariffs are available in only one time zone. However, some tariffs are offered in multiple time zones. For these tariffs, a UTC time zone will be returned.

Date Periods

We also support passing dates as periods of time. This feature is useful for passing usage data when running calculations, and these periods are added as an attribute of the propertyInputs being passed in. Date periods are strings that define the "notation" for the period, leveraging common notation used for defining, parsing, and formatting dates and times.

We are expanding support for date periods. Currently, 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 ... }