Ocean Update

10 min

The following notification will be posted as soon as FourKites logs a new milestone or tracking update on an ocean load. This correlates with the "Tracking Updates" section on the load card visible in the FourKites platform and is specific to the ocean mode.

{
    "BillOfLading": "ABCD123",
    "BookingNumber": "123456789",
    "ContainerNumber": "TCNU2728729",
    "ContainerType": null,
    "FourKitesLoadId": 8233886,
    "IMO": "9945837",
    "LoadNumber": "MM-4713_test1",
    "Message": "Container TCNU2728729 was loaded onto vessel SHADOW HUNTER",
    "MessageType": "OCEAN_UPDATE",
    "ProNumber": null,
    "ReferenceNumbers": [],
    "Scac": null,
    "Shipper": "oceanshipper",
    "Source": "Carrier",
    "Status": "Loaded on Vessel",
    "StatusCode": "AE",
    "StopName": "BEANR",
    "StopReferenceId": "",
    "StopType": "port_of_loading",
    "StopUnlocode": "INMAA",
    "Tags": [],
    "TerminalName": "TestTerminal",
    "Timestamp": "2022-10-22T15:08:44+02:00",
    "Timezone": "Europe/Brussels",
    "TimezoneOffset": 7200,
    "FourKitesDataSource" : "Carrier",
    "VesselName": "SHADOW HUNTER",
    "VoyageNumber": null
}

Note: The above sample callback is sent when the container is available for delivery. The other ocean load statuses for which a callback will be sent are:

Vessel Departure · Loaded on vessel · In-Gate · Out-Gate · Empty Equipment Dispatched · Estimated Delivery · Estimated Date Of Delivery To The Consignee Or Receiver · Carrier And Customs Release · Completed Unloading · Delivery Location Shipment Was Delivered To The Consignee Or Receiver · Return container · Unloaded From Vessel · Vessel Arrival

Refer to this article for more statuses

Field Definitions

Field Name	Data Type	Description	Expected Values	Conditions for this to be available	Nullable Field?
BillofLading	String	It indicates the bill of lading associated with the load.	Bill of lading reference	Load should have a Bill Of Lading populated This typically is provided by the shipper	Yes
BookingNumber	String	It indicates the shipping line's booking number.	Booking Number reference	Load should have a Booking Number populated This typically is provided by the shipper	Yes
ContainerNumber	String	Container Number of the Ocean load	Container Number	Load should have a Container Number populated	Yes
ContainerType	String	It indicates whether the container is a general, high cube, Reefer, etc.	20 20 Reefer 40 40HC 40HC Reefer 45 45HC 48 53 55 60	1. Load should have a Container Number populated

Container type info provided by the carrier source data | Yes | | FourKitesLoadId | String | Unique load identifier from the FourKites system | | | No | | IMO | String | International Maritime Organization number specific the the vessel assigned to the shipment | 9845679 | Whenever there is a Vessel data available. Populated for all four vessel related status codes: AE, VD, VA, & UV | No | | LoadNumber | String | Unique shipment identifier from shipper's system | | - Provided by shipper (or)

Container number is used as the load number | No | | Message | String | Indicates the tracking update details. For example, "Container TCNU2728729 was loaded onto vessel SHADOW HUNTER" | | | No | | MessageType | String | Indicates the type of the message. | OCEAN_UPDATE | | No | | ProNumber | String | PRO# found on the ocean load. | | This reference type is not applicable for Ocean loads | Yes | | ReferenceNumbers | Array | List of additional reference numbers associated with the load (empty list when no reference numbers are associated with the load) | Reference numbers provided by the customer for a given load | As provided by customer, else “null” | Yes | | Scac | String | SCAC of the carrier assigned to the shipment/load | * SCAC code of the carrier on the load (or)

If there are managing/operating carrier setup, this would be the SCAC code of the managing carrier on the load | | No | | Shipper | String | Unique shipper ID from FourKites | | | No | | Status | String | Status update | List of the status updates, refer to Ocean Update Callback | Documentation | Status Code. | | No | | StatusCode | String | Unique code for the status update | List of the status codes, refer to Ocean Update Callback | Documentation | Status Code. | | No | | StopName | String | Name of the stop provided during load creation | 1st priority: Customer provided stop name (or) 2nd priority: Carrier provided City name (or) 3rd priority: UNLOCODE | Will be populated only if the event is tied to a stop, else will be "null" | Yes | | StopReferenceId | String | It is the unique identifier of the stop from the customer's system. This populates the "Reference #" field on the stop and is used to indicate which stop an update is applied to. | Customer provided ID for a given stop | Will be populated only if the event is tied to a stop AND customer has provided a Stop reference ID for that stop, else will be "null" | Yes | | StopType | String | Indicator for the type of the stop | empty_pickup_location pickup place_of_receipt port_of_loading transhipment_port port_of_discharge place_of_delivery delivery empty_return_location | Will be populated only if the event is tied to a stop, else will be "null" | Yes | | StopUnlocode | String | It indicates the UNLOCODE of the stop | UNLOCODE (United Nations Code for Trade and Transport Locations) follows a specific format consisting of a two-letter country code and a three-character location code, eg: BEANR | 1. Will be populated only if the event is tied to a stop, else will be "null"

UNLOCODE will NOT be populated for Pickup and Delivery stoptypes | Yes | | Tags | Array | List of tags associated with the load (empty list when tags are not present) | Tags provided by the customer for a given load | As provided by customer, else “null” | Yes | | TerminalName | String | It indicates the terminal inside a port where the vessel is berthing (terminal name tied to a stop) | Name of the terminal | Applicable for events tied to following stoptypes * port_of_loading

transhipment_port

port_of_discharge | Yes | | Timestamp | String | The time when the event occurred For C1 and AG events, it is the ETD or ETA timestamp sent by carrier | Timestamp format will be the following: "2006-01-02T15:04:05-07:00" | Default ISO8601 format. | - Timestamp will be in stop's local time

If an event is not tied to a stop, then the timestamp will be in UTC | No | | Timezone | String | Timezone when the new milestone or tracking update was logged | Sample values: “America/New_York”, “Etc/UTC” Refer to this article for the list of timezones. | | Yes | | TimezoneOffset | Integer | It indicates the difference between local time and UTC in seconds | Sample values: “-18000”, “0” | If the stop's timezone is not available then the offset will be 0 in seconds | Yes | | VesselName | String | It indicates the name of the vessel carrying the load. | | Available with vessel events only (AE,VD,VA,UV) The VesselName field pertains to the currently active vessel assigned to the load. Therefore, they are exclusively accessible within milestones associated with the vessel for a specific transport leg | Yes | | VoyageNumber | String | It indicates the unique identifier given for the voyage. | | Available with vessel events only (AE,VD,VA,UV) The VoyageNumber field pertains to the currently active vessel assigned to the load. Therefore, they are exclusively accessible within milestones associated with the vessel for a specific transport leg | Yes |

FourKites Data Source List

List of Sources	Mapping Field
carrier_api dispatcher_updates_api superfile... And a few more.	"FourKitesDataSource" = "Carrier"
ds_inferred_events	"FourKitesDataSource" = "Inferred"
eta_propagation test_ocean_carrier geofence	"FourKitesDataSource" = "nil"

List of Milestones and StopType Matrix

The table below presents a list of milestones anticipated within the OCEAN_UPDATE callback, along with their corresponding associated stops

A few events are not anticipated to be associated with any stops, resulting in the absence of stop-related information in the OCEAN_UPDATE callback. The timestamp for these events will be in UTC.

You can download the list below:

Milestones & StopType Matrix.pdf