Defining the payload's facility field

This article describes what to expect from the "facility" field within the payload response from the API

What is the "facility" field?

The "facility" field is a string value as provided directly by the tracking source (carrier, AIS, or terminal) if available. It can be found as a property in the following two sections of the reference update payload:

  • the Location object of each milestone
  • the top-level "destination_port", "inland_origin", "inland_destination", and "origin_port" location objects 

An example location with a "facility" field looks like:

  "city": "Los Angeles",
  "country": "United States",
  "facility": "WBCT",
  "facility_code": null,
  "geolocation": {
    "latitude": 34.05223,
    "longitude": -118.24368
  "name": "Los Angeles",
  "raw_unlocode": null,
  "state": "California",
  "unlocode": "USLAX"

Is the "facility" field standardized?

The "facility" field is not standardized.

A null value means that we don't have facility information at that time, and we can not always expect to see this value populated.

This field comes through one of two ways:
  1. Mainly, it will populate as a pass-through from a carrier sourced event, but it is inconsistent when a carrier provides the facility in their location string. 
  2. The "facility" field will also populate via terminal sourced events. For that data, a non-null value will be much more consistent for the terminals that we've built connectivity too. 
We are not able to provide a mapping for facility to UNLOCODE as it is a much more fine-grained object than the port itself.
For example, UNLOCODE=USNYC refers to the port of New York. Within this port, there are over 10 ocean terminal facilities and 228 non-ocean terminal facilities making a 1:1 mapping impossible.
Additionally, due to the numerous facilities within a port, the ability to provide the facility value in the absence of info from the carrier is highly unlikely. There are so many scenarios when our estimate would be wrong. Overall, it is better to leave an event null than be incorrect.