Date/Time Formats

Overview

The Shipwell API accepts and returns dates/times properties in ISO 8601 date/time format in the UTC time zone, i.e. 2023-30-11T18:13:16.131103Z. These are the global standards for date/times in systems. Data is stored and returned in UTC as it is the global "neutral" time zone that all other time zones are relative to/from. For more information on time zones, time zone offsets, etc. see this link.

Date/Time Properties

In the Shipwell API, date/times are represented as ISO 8601 date/time strings in the UTC time zone (a Z or +00:00 at the end of the date/time string is the indicator for UTC). This is the expected format and time zone for most REST APIs. Here are some example date/time fields:

Copy

Copied

{
    "created_at": "2023-07-01T18:13:16.131103Z",
    "updated_at": "2023-07-01T18:13:18.159155Z",
    "completed_at": "2023-07-02T17:07:25.456712Z",
    "with_offset_example": "2023-07-02T17:07:25.456712+00:00"
}

Date/Time Offsets

If there is a specific localized event, a rare need or exception in the API, the time zone offset from UTC may be included in a date/time property's value. These offsets are relative to the UTC time zone. For example, the offset for UTC is zero or +00:00. Date/time parsers that handle ISO 8601 date/time formats will have the ability to parse time zone offsets built-in.

Date/Time Conversion to Another Time Zone

There are various use cases where an API caller may need to display or convert a UTC date/time property in an API response to a local time zone. For example, users in New York and in Los Angeles may need to see one or more date/times displayed in their local time zone (with daylight savings taken into account).

This is one of the benefits of storing and returning data in the common global ISO 8601 format in UTC as a time zone. Different business use cases around date/time conversion may be taken into account by the system handling the API response depending on the needs of that system. This is also why most modern REST APIs do not perform date/time conversion (as the conversion use cases are business specific).

Date/Time Conversion Libraries

JavaScript, Python, Java, etc. will all have date/time conversion functions and libraries that are built-in to the programming language or are packages that may be referenced in projects. For example:

Python has built-in functionality like ZoneInfo as well as packages like arrow
Java has built-in functionality like java.time as well as packages like Joda-Time
JavaScript has built-in functionality as well as modules or packages like Moment.js and Moment Time Zone

javascriptpythonjava

Copy

Copied

// Uses Moment.js and Moment Time Zone with Time Zone Data
var original = moment("2023-07-02T17:07:25.456712Z");
var losAngeles = original.clone().tz("America/Los_Angeles");
var newYork = original.clone().tz("America/New_York");

// ISO 8601 format in two different time zones
console.log(losAngeles.format()); // "2023-07-02T10:07:25-07:00"
console.log(newYork.format()); // "2023-07-02T13:07:25-04:00"

var jun = moment("2023-06-15T17:07:25.456712Z");
var dec = moment("2023-12-02T17:07:25.456712Z");

// daylight savings example
console.log(jun.tz('America/Los_Angeles').format('ha z'));  // 10am PDT
console.log(dec.tz('America/Los_Angeles').format('ha z'));  // 9am PST

Copy

Copied

import dateutil.parser
from zoneinfo import ZoneInfo

date_str = "2023-07-02T17:07:25.456712Z"
los_angeles_tz = "America/Los_Angeles"
new_york_tz = "America/New_York"

# python native
built_in_parsed_date = dateutil.parser.parse(date_str)
print(built_in_parsed_date)  # 2023-07-02T17:07:25.456712+00:00
utc_date = built_in_parsed_date.astimezone(ZoneInfo("UTC"))
print(utc_date.isoformat())  # 2023-07-02T17:07:25.456712+00:00

la_built_in_converted_date = utc_date.astimezone(ZoneInfo(los_angeles_tz))
print(la_built_in_converted_date.isoformat())  # 2023-07-02T10:07:25.456712-07:00

ny_built_in_converted_date = utc_date.astimezone(ZoneInfo(new_york_tz))
print(ny_built_in_converted_date.isoformat())  # 2023-07-02T13:07:25.456712-04:00

# Example with the "arrow" package
# import arrow
# 
# 
# date_str = "2023-07-02T17:07:25.456712Z"
# los_angeles_tz = "America/Los_Angeles"
# new_york_tz = "America/New_York"
# 
# parsed_date = arrow.get(date_str)
# print(parsed_date)  # 2023-07-02T17:07:25.456712+00:00
# print(parsed_date.humanize())  # N hours/days/etc. ago
# 
# la_converted_date = parsed_date.to(los_angeles_tz)
# print(la_converted_date)  # 2023-07-02T10:07:25.456712-07:00
# 
# ny_converted_date = parsed_date.to(new_york_tz)
# print(ny_converted_date)  # 2023-07-02T13:07:25.456712-04:00

Copy

Copied

# using Java 8+ and java.time

import java.time.ZonedDateTime;
import java.time.ZoneId;
import java.time.format.DateTimeFormatter;

String dateStr = "2023-07-02T17:07:25.456712Z";
String losAngelesTz = "America/Los_Angeles";
String newYorkTz = "America/New_York";

// Parse the date string as a ZonedDateTime
ZonedDateTime parsedDate = ZonedDateTime.parse(dateStr, DateTimeFormatter.ISO_DATE_TIME);
System.out.println(parsedDate);  // 2023-07-02T17:07:25.456712Z

// Convert to UTC time zone (already in UTC in this case)
ZonedDateTime utcDate = parsedDate.withZoneSameInstant(ZoneId.of("UTC"));
System.out.println(utcDate);  // 2023-07-02T17:07:25.456712Z

// Convert to Los Angeles time zone
ZonedDateTime laConvertedDate = utcDate.withZoneSameInstant(ZoneId.of(losAngelesTz));
System.out.println(laConvertedDate);  // 2023-07-02T10:07:25.456712-07:00

// Convert to New York time zone
ZonedDateTime nyConvertedDate = utcDate.withZoneSameInstant(ZoneId.of(newYorkTz));
System.out.println(nyConvertedDate);  // 2023-07-02T13:07:25.456712-04:00