Formatting

Timestamps

Vizion provides timestamps in the ISO8601 format so that most languages' standard date libraries should be able to parse them directly without any extra work. The value for timestamps can come in three potential forms, depending on the level of enrichment Vizion was able to provide:

Timestamp is null
If you receive a null value for a timestamp Vizion was not able to locate date and time information for this event or the information found could not be parsed.

Timestamp is formatted as yyyy-MM-dd'T'HH:mm:ss.SSSZ (e.g. "2021-01-17T23:58:00.000Z")
If date and time information is available but no further location information could be determined to identify the timezone in which the event occurred the timezone will be set to UTC.

Timestamp is formatted as yyyy-MM-dd'T'HH:mm:ss.SSS+/-ZZ:ZZ (e.g. "2021-01-17T23:58:00.000+08:00")
All information for date, time, and location have been found and are reported in the timezone in which the event occurred. The offset provided quickly allows for conversion to UTC.

📘

Date-only events

Some carriers report certain events with a date but no time of day. When this happens, the time is set to 00:00:00 in the timezone of the event location, for example "2026-08-20T00:00:00.000+07:00". If the timezone could not be determined, the value is set to UTC as described above.

A time of 00:00:00 means the date is confirmed but the carrier did not provide a time; it does not mean the event occurred at midnight, and it does not indicate a timezone shift. Two events on the same date may both show 00:00:00 even though they happened at different times.

If you need to order events that fall on the same date, don't rely on the timestamp alone. Use shipment_location.type_code and journey_event.event_type to determine their sequence.

container_iso property

The container_iso values that our API returns are provided by the carriers themselves and should be standardized according to the Container Services International definition located here.

For example, a "container_iso" value of "22G1" means the length is 20 feet, the height is 8 feet 6 inches, and the container overall is intended for general purposes.