Location Update

4 min

When a new location is available for a load, the following notification will be triggered.

{
    "MessageType": "LOCATION_UPDATE",
    "FourKitesLoadId": 1234,
    "LoadNumber": "BOL12345",
    "ContainerNumber":"BEAU5912889",
    "dataSource": "fourkites-x",
    "ProNumber": "PRO123",
    "Shipper": "test-shipper",
    "Tags": ["tag1", "tag2"],
    "ReferenceNumbers": ["Ref1", "Ref2"],
    "Location": "123 Address Street, New York, NY, USA",
    "City": "New York",
    "State": "NY",
    "Country": "USA",
    "Latitude": "40.7127",
    "Longitude": "-74.0059",
    "OdometerReading": 12345,
    "Timestamp": "2015-10-01T16:00:00-05:00"
    "Timezone": "America/New_York",
    "TimezoneShortName": "EST",
    "TimezoneOffset" : -1800
}

Rail-specific parameters on RAIL loads can be sent as part of this callback. However, note that although these parameters can be sent in the callback for companies that are licensed for RAIL tracking, they are not available by default. If your company is licensed for RAIL tracking and would like to take advantage of this feature, get in touch with your Customer Success Manager at FourKites to have it enabled.

Below is a sample callback including the rail specific parameters (highlighted):

{
    "MessageType": "LOCATION_UPDATE",
    "FourKitesLoadId": 1234,
    "LoadNumber": "BOL12345",
    "LoadedEmpty": "E",
    "RailDestinationCity": "Rivers",
    "RailDestinationState": "MB",
    "RailEquipment": "RAIL0011",
    "RailEvent": "Constructive Placement",
    "RailStation": "Rivers",
    "ProNumber": "PRO123",
    "Shipper": "test-shipper",
    "Tags": ["tag1", "tag2"],
    "ReferenceNumbers": ["Ref1", "Ref2"],
    "Location": "123 Address Street, New York, NY, USA",
    "City": "New York",
    "State": "NY",
    "Country": "USA",
    "Latitude": "40.7127",
    "Longitude": "-74.0059",
    "StatusCode": "X6",
    "OdometerReading": 12345,
    "Timestamp": "2015-10-01T16:00:00-05:00"
    "Timezone": "America/New_York",
    "TimezoneShortName": "EST",
    "TimezoneOffset" : -1800,
    "TrainID": "Q19919"
}

Field Definitions

Field Name	Description	Key Always Present?	Value Always Present?	Conditions for the Key to be Present	Data Type	Max Length
City	Nearest city to the location update. Will be approximate if not an exact location	Yes	No	N/A	String	1024
Country	Country associated with the location update	Yes	No	N/A	String	1024
FourKitesLoadId	FourKites generated unique Load ID	Yes	No	TrackingId will be mapped to FourKitesLoadId	Int64	9
Latitude	Decimal latitude of the location update	Yes	Yes	N/A	Int64
LoadNumber	Customer supplied Load Number. This is populated on the Create Load API	Yes	Yes	N/A	String	65535
Location	The name of the current location. Oftentimes this is supplied by the carrier, but can also be the latitude/longitude coordinates if not supplied	Yes	Yes	N/A	String	1024
Longitude	Decimal longitude of the location update	Yes	Yes	N/A	Int64
OdometerReading	Odometer reading associated with the check call (provided only for loads moved by dedicated carriers)	Yes	No	N/A
ProNumber	PRO Number associated with the load	Yes	No	N/A	Number	10
ReferenceNumbers	List of unique identifiers for the load. These can be used to search for the load the platform	Yes	No	N/A	Array of string	No max
Scac	SCAC or identifier for the carrier	Yes	No	N/A	Alpha/Numeric	4
Shipper	Unique permalink for the company. This is generated by FourKites and is unique for each company	Yes	No	N/A	String	No max, but realistically, not longer than 200 characters
State	State/province associated with the location update	Yes	No	N/A	String	1024
Tags	List of categories or labels for the load	Yes	No	N/A	Array of string	50 for each tag
Timestamp	Time that the location update was received. This will be in the local time of the location ping	Yes	Yes	The LocatedAt time will be mapped to Timestamp after converting it to customer specific Timezone.	ISO8601 Date/Time	30
Timezone	Time zone in which the location was logged	Yes	Yes	N/A	String	50
TimezoneOffset	Numeric offset (in seconds) of the time zone in which the location was logged	Yes	No	This will be mapped based on the Timestamp received. The Timestamp will be converted to a specific timezone and will be mapped to TimezoneOffset	[+/-]Digits	10
TimezoneShortName	Time zone short name in which the location was logged	Yes	No	If Timestamp or Timezone is nil then TimezoneShortName will be empty	String	5
StatusCode		No	Yes	Carrier should not be null and the field parcel provider should not be null. If it is not null, StatusCode key will be present in the callback payload and the value will always be X6.	String	50 at max
deviceID	DeviceID assigned to the load	No	No	For the deviceID field to be present, the tracking method should be received as device id from the customer. Only in that case, the device id will be mapped.	String
ReportingRailroad		No	No	ReportingRailRoad will be mapped based on the additional data received from the customer -- this should not be be null. This is a feature_flag	String
LoadedEmpty	Rail car loaded empty	No	No	LoadedEmpty field will be mapped based on the additional data & Loaded/Empty status from the customer -- this should not be be null. This is a feature_flag	String
RailStation	Latest Rail Station on the load	No	No	RailStation field will be mapped based on the additional data & station name from the customer -- this should not be be null. This is a feature_flag	String	30 at max
TrainID	Train's Unique ID	No	No	TrainID will be mapped based on the additional data & trainID from the customer -- this should not be be null. This is a feature_flag	String
RailEventCode		No	No	RailEventCode will be mapped based on the additional data & event code from the customer -- this should not be be null. This is a feature_flag	String	4 at max
RailDestinationStation	Rail destination stop name given on the load	No	No	RailDestinationStation will be mapped based on the additional data & destinationCity from the customer -- this should not be be null. This is a feature_flag	String	30 at max
RailDestinationState	Destination State of the rail leg of the load	No	No	RailDestinationState will be mapped based on additional data & destinationState from the customer -- this should not be be null. This is a feature_flag	String	2 at max
ReceivedDateTime		No	No	ReceivedDateTime will be mapped based on the additional data & sentTimeStamp from the customer -- this should not be be null. This is a feature_flag.	String
RailEvent	Latest Rail Event on the load	No	No	This is a feature_flag.	String	4 at max
RailEquipment	Rail Equipment Number assigned to the load	No	No	RailEquipment will be mapped if railEquipmentIntials & RailEquipmentNumber are received from the customer -- this should not be be null. Provided the fields received are hyphenated. - feature_flag
BookingNumber	Booking number provided for tracking the shipment	Yes	Yes	These keys will be present only for Ocean-specific loads.	String	1024
VoyageNumber	Number of the voyage for the vessel the shipment is currently loaded on	Yes	Yes	These keys will be present only for Ocean-specific loads.	String	1024
VesselName	Name of the vessel the shipment is currently loaded on	Yes	Yes	These keys will be present only for Ocean-specific loads.	String	1024
ContainerType	Type of the container in which the shipment is loaded	Yes	Yes	These keys will be present only for Ocean-specific loads.	String	1024
ContainerNumber	Number of the container in which the shipment is loaded	Yes	Yes	These keys will be present only for Ocean-specific loads.	String	1024
BillOfLading	MBOL or HBOL provided for tracking the shipment	Yes	Yes	These keys will be present only for Ocean-specific loads.	String	5
CreatedBy	This applies only for FourKites X loads.			The CreatedBy field will be available and sent only for FourKites X licensed customers — this is to identify between FourKites X and non FourKites X loads.	String	1024

Note: The Country Code and State Code sent in the callbacks will be internationally recognized codes as per ISO 3166.

Update Frequency

By default, FourKites sends the last received location update once in 15 minutes. However, if you wish to receive fewer location updates, contact your CSM/SC. The minimum and maximum values that can be set are 15 minutes and 720 minutes respectively.

Example: If you want to set the update frequency to 60, then you will receive a location update once every 60 minutes only. This will be the last received location of the vehicle at that point in time.