Dates & Times

Format Switch API date and time values with ISO 8601 strings, explicit time zones when possible, and inclusive fromDateTime / exclusive toDateTime ranges.

Use these conventions when you send date ranges for account rates, tariffs, calculations, savings analyses, profile readings, and other time-based Switch resources. If you are choosing where to start, see Getting Started.

Date formats

Switch supports the ISO 8601 format for dates and times. Use the level of detail your request requires, from a year-only value to a full timestamp with milliseconds and a time zone.

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

yyyy-MM-ddTHH:mm:ss.SSSZ

Defaulting

Use the full date, time, and time zone whenever possible. When a field is not specified, Switch defaults to the earliest possible value. For example, if you do not specify a time of day, Switch defaults to T00:00:00 (midnight).

If the time zone is not specified, Switch defaults the time zone according to the context of the call. For calculations and savings analyses, dates without a time zone default to the time zone of the tariff (masterTariffId) used in the calculation. This is the Tariff Time Zone. When there is no appropriate tariff context, the time zone defaults to UTC, an offset of 00:00.

This table shows valid date and time inputs and their UTC equivalents when the time zone defaults to UTC:

This table shows valid date and time inputs when Switch 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 is Pacific Daylight Time (-07:00) for summer dates and Pacific Standard Time (-08:00) for winter dates.

Validate a date or time format with the Validate Input Formats endpoint. For HTTP request parameters, URL-encode the input when needed, especially when using a UTC+ time zone offset. The + character must be encoded as %2B.

Date ranges

Represent date ranges with fromDateTime and toDateTime. The fromDateTime is inclusive, and the toDateTime is exclusive. The range includes the instant of fromDateTime and does not include the instant of toDateTime.

This rule also applies to other dates in Switch schemas. A Tariff with an effectiveDate of 2015-01-01 and an endDate of 2015-04-01 is effective on January 1 and March 31, but is no longer effective on April 1.

Arcadia-style date ranges match the ISO 8601 start/end interval convention. 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 account cost calculation or mass calculation request, response dates and times are returned in the tariff's time zone. You can send request dates and times with a different time zone, and Switch will use them in the calculation request, but the response will use the tariff's time zone.

Most tariffs are available in only one time zone. For tariffs offered in more than one time zone, the response returns a UTC time zone.

Date periods

Switch also supports passing dates as periods of time. This can be useful when passing usage data for calculations. In this case, date periods are added as an attribute of the TariffInput passed in the request.

Date periods use a string that defines the notation for the period. This notation is used for defining, parsing, and formatting dates and times.

Switch currently supports this date period syntax:

• e: Day of the week, from 1 (Mon) to 7 (Sun)
• H: Hour of the day, from 0 to 23
• 1:5: Weekdays
• 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 */ }
// Additional hourly weekday periods omitted.
{ period: "1:5e 22H", /* other fields */ }
{ period: "1:5e 23H", /* other fields */ }
{ period: "6:7e 1H", /* other fields */ }
{ period: "6:7e 2H", /* other fields */ }
// Additional hourly weekend periods omitted.
{ 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, use the optional groupBy and clipBy parameters to control boundary readings. These parameters control whether to include inner readings that are completely contained in the requested intervals or outer readings that contain the requested intervals but extend beyond them.

For more details, see the Profiles API documentation.

Next steps

1. Review Requests for URL encoding, query parameters, and request-body conventions.
2. Use Testing & Debugging Overview or Validate Input Formats to test a date-time value before sending it to a resource API.
3. Review Responses to handle date-range validation errors such as InvalidDateRange.