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.
The full representation of a date and time is in 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:
| Sample | Description |
|---|---|
| 2011 | Equivalent to 2011-01-01T00:00:00.000+00:00 |
| 2011-06 | Equivalent to 2011-06-01T00:00:00.000+00:00 |
| 2011-06-23 | Equivalent to 2011-06-23T00:00:00.000+00:00 |
| 2011-06-23T18 | Equivalent to 2011-06-23T18:00:00.000+00:00 |
| 2011-06-23T18:45 | Equivalent to 2011-06-23T18:45:00.000+00:00 |
| 2011-06-23T18:45Z | Equivalent to 2011-06-23T18:45:00.000+00:00 (UTC time zone) |
| 2011-06-23T18:45+0000 | Equivalent to 2011-06-23T18:45:00.000+00:00 (UTC time zone) |
| 2011-06-23T18:45-0700 | Equivalent to 2011-06-23T18:45:00.000-07:00 (Pacific Daylight Time time zone) |
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 the 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.
| Sample | Description |
|---|---|
| 2011 | Equivalent to 2011-01-01T00:00:00.000-07:00 |
| 2011-06 | Equivalent to 2011-06-01T00:00:00.000-07:00 |
| 2011-06-23 | Equivalent to 2011-06-23T00:00:00.000-07:00 |
| 2011-06-23T18 | Equivalent to 2011-06-23T18:00:00.000-07:00 |
| 2011-06-23T18:45 | Equivalent to 2011-06-23T18:45:00.000-07:00 |
| 2011-06-23T18:45Z | Equivalent to 2011-06-23T18:45:00.000+00:00 (UTC time zone) |
| 2011-06-23T18:45-0700 | Equivalent to 2011-06-23T18:45:00.000-07:00 (PDT time zone) |
| 2011-01-23 | Equivalent to 2011-01-23T00:00:00.000-08:00 (winter, PST time zone) |
To validate if the 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 "Arcadia-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 an on-demand cost calculation or mass calculation 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 Calculator 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 that 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 properyInputs 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 ... }