Introduction

The purpose of this document is to provide additional information around how Convey handles time zone and timestamp data received from carriers, and how that data will surface in Convey's UI and APIs. 

Definitions

First, let's start by defining the common terms that are referenced when we talk about time zones and timestamp information as it relates to data in Convey. 

• Carrier Tracking Event: An event received from a carrier that represents a change and/or movement for a shipment (e.g. scheduled, in transit, out for delivery, delivered). A carrier tracking event is provided by a carrier through the carrier-Convey tracking integration (e.g. API or a Flat File Feed). A carrier tracking event typically contains a status and/or exception code, event description, an event time and an event location.
• Event Time: The time of an event is a combination of the local date, local time and time zone UTC offset. All together, the local date, time and UTC offset represent a specific day and time in a particular time zone (i.e. the Event Time) and can also be referred to as the Timestamp. For example “5:07 PM in Central Time on June 23rd” represents a specific day, time and time zone. Whether or not the local date, local time and UTC offset all are available for an event is dependent on the type of event and the carrier technology used to store and make available its tracking events to Convey. 
• Timestamp: A specific moment in time, for example “5:07 PM in Central Time on June 23rd”, which can be translated to be the same moment in time in a different location as “6:07 PM in Eastern Time on June 23rd”. These are the same Timestamp, but have a different Event Time due to the location. 
• Local Date: Represents a day, which must be used in conjunction with local time and a time zone or a geographic location to represent a particular timestamp. For example “June 23rd” will start and end at different moments in different time zones.
• Local Time: Represents a time of day, which must be used in conjunction with local date and a time zone or a geographic location to represent a particular timestamp. For example “5:00 PM” will happen at different moments in different time zones.
• UTC Offset: A value in hours and minutes which represents the difference between a specific time zone and the Universal Time Coordinated (UTC), which is represented as an offset of 0 or Z (Zulu Time). For example, the US Central Time has a UTC offset of -5 hours during the summer (daylight savings time) and -6 hours during the winter.
• Time zone & UTC offset: A time zone and a UTC offset are equivalent, however a UTC offset can be more accurate since it is self-contained. A time zone may be confusing and incorrect when, for example, “EDT” (during summer, -5 hours) and “EST” (during winter, -6 hours) are used interchangeably even though their UTC Offsets are different. Additionally, time zones within a UTC offset are communicated differently by country. For example, a UTC Offset of -4 hours would be represented as EST or EDT if the event occurred in NY, AST or AMT if it occurred in Brazil, PYT if it occurred in Paraguay, and BOT if it occurred in Bolivia. 
• Event Location: The geographic location of an event. For example, “Austin” (city), “TX” (state or province code) and “US” (country code) is an event location. When used in conjunction with a local date and local time, the geographic location can usually be used to derive a UTC offset if it is unavailable from the carrier data. For example “5:07 PM on June 23rd” in “Austin, TX” is equivalent to “5:07 PM in Central Time on June 23rd” - hence a UTC Offset of -5 hours, which is a timestamp. Because some time zone boundaries can cross specific locations, the geographic location must be precise to be used to derive the UTC offset. For example, some US states have multiple time zones so the state itself would not be sufficient (some time zones also cross cities, although it is rare).

Locality of Event Times

Similar to how most carriers display event times in their own system/portal, the Convey platform displays event times as local to the corresponding carrier tracking event.

For example, if an event shows in the carrier system or on the carrier website as having happened at 1:32 PM on June 24th in Austin, TX it will be represented as follows:

• Local date: June 24th
• Local time: 1:32 PM
• UTC offset: -5 hours

Accordingly, when Convey receives and processes the carrier tracking events, the Convey platform will translate the events to the local time if appropriate and possible.

For example, if the carrier provides this information for a given event:

• 1:32 PM on June 24th in the Pacific Time Zone (-7 hours) in Austin, TX

Then the Convey platform will translate the event to:

• Local date: June 24th
• Local time: 3:32 PM
• UTC offset: -5 hours

The local time is set to 3:32 PM and the UTC offset is set to -5 hours since the location is known as Austin, TX, which is in the Central Time Zone; this represents a more correct local time for this event.

Important Note: if the local date, local time and UTC offset are available then it is possible to translate the event time into any time zone for further processing, for example to compute a timestamp at UTC or to show a carrier tracking event into a different time zone (maybe a time time zone local to a customer). 

Accuracy and Granularity of Event Times

When carrier tracking events are processed by the Convey platform, they are represented by the most accurate Event Time possible based on the information provided by the carrier. This means that if the carrier provided a local date, local time and UTC offset OR a timestamp for a the carrier tracking event, the same granularity will be available in Convey. Conversely, if the carrier fails to provide any of this information, then information provided will be accurately represented in Convey and no event time information will be created or misrepresented.

Depending on the carrier and the carrier tracking event, different levels of information may be available. Therefore, the Convey platform provides a flexible representation of event times:

• Local date: the local date of the event - optional, but always provided by the carrier
• Local time: the local time of the event - optional, but often provided by the carrier
• UTC offset: the UTC offset of the event - optional, but always provided by parcel carriers and often provided by freight and white glove carriers.

If a local date, local time and UTC offset are provided, we will combine together to produce a timestamp

Additionally, if the carrier provides a geographic location for a carrier tracking event (e.g. city and state, or province code or postal code) and the UTC offset is missing, the Convey platform will attempt to retrieve the time zone information and make the UTC offset available.

Important Note: Some carrier tracking events simply do not have timestamps. In the example below, the FedEx “Shipment information sent to FedEx” event has a local date and local time, but no location or UTC offset. In this case, “local” represents the local date and time of the IT system that processed the request.

Event Time Examples

The table below provides a mapping of what is provided by the carrier and what will then be available in Convey UIs and APIs. 

Scenarios:

1. Carrier provides local date, local time and UTC offset
   • Convey provides local date, local time, UTC offset (together a timestamp)
2. Carrier provides local date only
   • Convey provides local date only
3. Carrier provides local date and local time only
   • If an event location is provided and can be used to determine a time zone, then Convey provides local date, local time, UTC offset (together a timestamp)
   • If an event location is not provided or cannot be used to determine a time zone, then Convey provides local date only
4. Carrier provides a timestamp
   • Convey provides local date, local time, UTC offset (together a timestamp) 

Timestamp Formats

The Convey platform supports the the ISO 8601 format:

• Local date: 2021-06-24 (YYYY-MM-DD)
• Local time: 14:23:00 (hh:mm:ss.sss)
• UTC offset: -05:00 (+/-hh:mm) - also Z for UTC (offset of 0)
• Timestamp: 2021-06-24T19:23Z or 2021-06-24T14:23-05:00 (YYYY-MM-DDThh:mm:ss.sss+/-hh:mm)

When an object is created in the Convey platform (e.g. a shipment or shipment event), the timestamp of when that object was created is generated and available as a timestamp in the 'created_date_time' field. The Convey APIs provide each of these fields separately - the created_date_time, the local_date, the local_time and utc_offset. See the example response below from the Retrieve Shipment API:

In this example, the “Picked up” event for this shipment occurred on June 21st at 13:15 in Eastern Time (-04 hours). Location information was also available and extracted. 

As an alternative example, and for historical reasons, the Tracking API only provides the local_date_time and created_date_time fields. 

The local_date_time field represents both the local date and the local time together, and will match the local date and local time elements in other Convey APIs. If a local time isn’t available, then the local time will be defaulted to 00:00, e.g. “2021-06-03T00:00”. This is only the case for the Tracking API response.

In order to fully represent the original event time, all future Convey APIs will provide the local date, local time and UTC offset as separate elements, which are omitted when they are not available (i.e. no default value will be assigned).

Time Zones & UTC Offsets

A time zone and a UTC offset are equivalent, however a UTC offset can be more accurate since it is self-contained. A time zone may be confusing and incorrect when, for example, “EDT” (during summer, -5 hours) and “EST” (during winter, -6 hours) are used interchangeably, even though their UTC Offsets are different. For this reason, the Convey platform only provides a UTC Offset through its APIs (not the time zone name) since the appropriate time zone can be determined by using the local date, local time and UTC offset.

See below some relevant examples:

• A June 24th date with a UTC offset of -5 hours can be determined to be the Central Daylight Time (CDT) timezone
• Am October 24th date with a UTC offset of -6 hours can be determined to be the Central Standard Time (CST) timezone
• Related to the above examples, on specific days where the Daylight Savings apply the local time can be used to determine whether the time zone is CDT or CST based on the time of day (since Daylight Savings switches at 2 AM on the day).

Time Zone Display | Shipment Details UI View

If Convey receives a number of carrier events in a single API call, and the API response does not order the events naturally (e.g. "In Transit" event shows after "Scheduled" event), it requires Convey to add custom logic in the tracking integration so that the events will be ordered properly and created in the same order. Once added, the events will be sorted as expected in Shipment Details page. 

FAQs

Why is either the local date, local time or UTC offset missing in the API response?

When processing carrier tracking events, the time information is extracted from the information provided by the carrier. When the local date, local time and UTC offset are available, that information will be reflected in Convey. However, if the time or UTC offset were not provided, then those will be missing. Here are examples:

This is to be expected because the information provided by the carrier may not contain the full timestamp information, or couldn’t be extracted due to a change.

For some specific carriers or carrier events, time information may never be present. For example, USPS may only provide a local date for certain events.

While we make every effort to capture the full extent of the information provided by the carrier it may have been unavailable for certain events, or unavailable due to a change or technical issue. All consumers of the Convey APIs should gracefully handle each of those elements being unavailable and implement strategies to handle each edge case.

If you require further investigation, you may contact Convey Support (support@getconvey.com) to request  confirmation as to why a specific element for a carrier event is unavailable.

Why is either the city or state or province code missing in the API response?

When processing carrier tracking events, the location information is extracted from the information provided by the carrier. When a city, state or province code is not provided, or if (for example) a postal code is used to find the corresponding city and state and the province code is not recognized, then the location information will be incomplete.

In some instances, the city, state and/or province code is missing. Here are examples:

This is to be expected because the information provided by the carrier is not always complete, or couldn’t be extracted due to a change.

While we make every effort to capture the full extent of the information provided by the carrier it may have been unavailable for certain events, or unavailable due to a change or technical issue. All consumers of the Convey APIs should gracefully handle each of those elements being unavailable and implement strategies to handle each edge case.

If you require further investigation, you may contact Convey Support (support@getconvey.com) to request  confirmation as to why a specific element for a carrier event is unavailable.