How do I read the JSON update payload?

This guide walks through the structure of the real-time, standardized, and detailed container milestone events delivered by the Vizion API in JSON format.

Vizion API's JSON output is designed to be easily interpreted by both machines and humans alike, making it versatile and convenient to use with any language or system. Once you understand the key components of the payload, the format is intuitive and straightforward to navigate.

This article walks through the structure of the JSON returned via webhook when subscribing to a container by Carrier Code, Auto Carrier Identification, or Bill of Lading. The List Reference Updates endpoint can also be used to retrieve the entire series of update payloads for a given reference.

See our developer object reference for more details.

Top level properties

The top-level properties of the JSON delivered to your callback URL include a unique id to represent the particular update, a reference_id for the container being tracked, and an organization_id that represents your organization's account with Vizion.

{
 "id": "b274e1f6-1426-4d50-9eda-18e325fbe269",
 "status": "data_received",
 "reference_id": "e8991c95-5db2-4c0c-8a02-119611f769df",
 "organization_id": "3670867f-3634-4dd2-9b27-3531b5affe64",
 "payload": {...},
 "created_at": "2023-01-16T21:01:01.547Z",
 "updated_at": "2023-01-16T21:01:01.547Z",
 "parent_reference_id": null
}

When receiving the data via webhook, the status property always equals 'data_received' because data for the container has been found and posted to your callback URL.

If you are not receiving data to your callback URL and want to investigate further, the Show Reference Details endpoint can be used to figure out why you have not received an update. In these cases, the last_update_status property is 'no_data', 'extraction_failed', 'webhook_failed', 'duplicate_payload', or 'auto_carrier_not_found'. See the API documentation for more details on the meaning of each status.

If the reference is created via Bill of Lading, the parent_reference_id represents the reference created for the Bill of Lading. If created without the Bill of Lading, the parent_reference_id is null.

Update payload

The payload object contains all of the important information related to your container's journey. It describes the container and carrier (container_id, container_iso, carrier_scac), the ID of the reference, and the origin and destination (inland_origin, origin_port, destination_port, inland_destination).

If bill of lading is null as in the example below it means it wasn’t provided and the container is being tracked using the container ID and carrier code.

{
  "bill_of_lading": null,
  "carrier_scac": "MSCU", 
  "container_id: "MEDU8381210, 
  "container_iso": "40' HIGH CUBE', 
  "milestones": [...], 
  "reference_id": "68854943-1d28-48c1-8e0a-ebee10b23f11",
  "destination_port": {...},
  "inland_origin": {...},
  "inland_destination": {...},
  "origin_port": {...}
}

Milestones

The array of milestone objects included within the payload describes the key events of the container. These milestones provide a comprehensive view of the container’s progress and allow for the tracking of its movement from origin to destination.

The description is a standardized and enriched description of the milestone event based on the raw_description, which is provided by the carrier. If Vizion cannot standardize the carrier description and we do not recognize the event, the carrier description is provided instead. We have eight core milestones that we attempt to include in each payload and expect to receive from the carrier, but you may find any events in this comprehensive list within your payload. Below is an example of a milestone object:

 {
   "timestamp": "2023-01-04T01:45:00.000+00:00",
   "location": {...},
   "description": "Loaded on vessel at origin port",
   "raw_description": "Loaded",
   "vessel": "CT ROTTERDAM",
   "vessel_imo": "9395575",
   "vessel_mmsi": "209836000",
   "voyage": "EB1230103",
   "planned": false,
   "mode": "Vessel",
   "source": "carrier"
}

When a milestone event has a planned value equal to true, this means that this is an estimated event that has not yet taken place. When planned equals false, this is an event that has already occurred.

 {
  "timestamp": "2023-01-06T01:00:00.000+01:00",
  "location": {...},
  "description": "Estimated vessel arrival",
  "raw_description": "Estimated vessel arrival",
  "vessel": "CT ROTTERDAM",
  "vessel_imo": "9395575",
  "vessel_mmsi": "209836000",
  "voyage": null,
  "planned": true,
  "mode": "Vessel",
  "source": "ais"
}

For more information on ETAs, see How can I find ETA to destination port information within the JSON payload?.

The source property describes the data provider for the milestone and is one of 'ais', 'terminal' or 'carrier'.

Location

A location object is included with each milestone and with the origin/destination ports or inland locations. To generate this object, Vizion takes location information received from the carrier and enriches it.

{
  "name": "Ensenada, Mexico",
  "city": "Ensenada",
  "facility": null,
  "state": "Baja California",
  "country": "Mexico",
  "unlocode": "MXESE",
  "geolocation": {
    "latitude": 31.8654499053955,
    "longitude": -116.59342956543
  }
}

UNLOCODEs are assigned by the UNECE and are used to identify ports, rail and road terminals, airports, and other locations for the purpose of shipping and logistics (see codes by country). Each unlocode property is made up of five letters, with the first two representing the country and the last three further specifying the location.

Also included with the location information is the geolocation object, which contains the coordinates of where the event has occurred.