BNSF

Provider Information:

Id	bnsf
Type	terminal
Trace Type	API
Credentials	Envase based, uses certificate and certificate key
Limits	Maximum number of containers per request is 100. Also, BNSF API has the folowing limits: 1 API Request Per Second, Per Partner, Per Service 15 API Requests Per Minute, Per Partner, Per Service 100 API Request Per Minute, Per Service
Status	completed
Doc Status	draft
Doc Version	1

URLs:

Type	URL	Environment
Request	https://https://api.bnsf.com:6443/	DEV/STG/PRD

Sites:

Name	Site Id	Description
name	ern	the description

Query Containers Request

Query containers using the request by adding the access token from the previous request in the headers as following.

POST https://https://api.bnsf.com:6443/v3/unit-details

{
    "intermodalUnits":[
        {
            "equipmentInitial": "{4 chars from the start of container number}",
            "equipmentNumber": "{6 chars from the end from container number}"
        }
    ]
}

Note

Container number splits into 2 parts of 4 and 6 chars and used in the payload

Responses

The success response for all the events is similar

{
"intermodalUnits": [
        {
            "equipmentInitial": "MEDU",
            "equipmentNumber": "226588",
            "originStation333": "OAKINTGAT",
            "originStationStateCode": "CA",
            "destinationStation333": "ALLIANCE",
            "destinationStateCode": "TX",
            "equipmentLotRowSpotTierStatusName": "Not Stacked",
            "derivedEquipmentStatusName": "Not in BNSF Inventory",
            "shipper633": "MEDITESHICOU",
            "carKindCode": "KG1",
            "loadEmptyChassisCode": "L",
            "equipmentLengthFeet": "20",
            "equipmentOutsideHeightFeet": "08",
            "equipmentOutsideHeightInches": "06",
            "equipmentGrossScaleWeightPounds": "50291",
            "shipmentNetScaleWeightPounds": "45291",
            "fullWaybillIndicator": "Y"
        }
    ]
}

Query Outgated Containers Request

Query outgated information about specific containers using the request by adding the access token from the previous request in the headers as following.

POST https://https://api.bnsf.com:6443/v1/j1-receipts

{
  "unitList": [
    "SEKU582192",
    "MSDU873627"
  ],
  "endDate": "2023-08-17",
  "startDate": "2023-08-10",
  "j1ReceiptData": true,
  "j1ReceiptPdf": false
}

Note

endDate number should represent today date and startDate should represent 7 days before today date

Response

{
    "j1Details": [{
        "unitInitial": "TTBN",
        "unitNumber": "200004",
        "j1Receipt": {
            "unitInitial": "TTBN",
            "unitNumber": "200004",
            "attachedUnit": {
                "unitInitial": "TJPZ",
                "unitNumber": "491216",
                "hazmatIndicator": false,
                "badOrderIndicator": false,
                "fullBilledIndicator": false
            },
            "station333": "STLOUIS",
            "stationStateCode": "MO",
            "destinationStation333": "STLOUIS",
            "destinationStateCode": "MO",
            "eventCode": "OG",
            "eventDate": "2023-08-09",
            "eventTime": "12:22:00",
            "truckCarrierScac": "FGMC",
            "shipper633": "CMACGMAMELLC",
            "carKindCarTypeCode": "K",
            "loadEmptyChassisCode": "L",
            "lengthFeet": "40",
            "grossWeightPounds": "57196",
            "hazmatIndicator": false,
            "badOrderIndicator": false,
            "fullBilledIndicator": false,
            "ingateSealNumber": "R0285156S",
            "releaseNumber": "9447F6",
            "loadSheetTofcWeightPounds": "64696",
            "loadSheetCofcWeightPounds": "57196",
            "tofcCofcCode": "C",
            "trueKingPinIndicator": 36,
            "axleLengthInches": "096",
            "stopOrderDescription": "Stg Due 08/10/23 DAYS 1-2/$150 DAYS 3+/$225",
            "equipmentControlCode": "I",
            "driverLicenseNumber": "A137017001",
            "tractorLicensePlateNumber": "105",
            "destinationReleasedCustomer633": "CMACGMAMELLC",
            "railControlledCode": "N",
            "patron633": "CMA CGM (AME",
            "patronName": "BNSF RAILWAY COMPANY",
            "intermodalUnitCertificationDate": "2023-07-25",
            "commodityDescription": "FAK",
            "shipmentLadingWeightPounds": "49096",
            "agsDefectFoundIndicator": "N",
            "truckNumber": "928",
            "carInitial": "BNSF",
            "carNumber": "270553",
            "platformCode": "A",
            "platformPositionCode": "1",
            "intermodalEquipmentProviderDOTNumber": "1521807"
        }
    }]
}

Data Mapping:

Property	Source Property	Description
container_number	equipmentInitial + equipmentNumber	The container number.
description		empty string
loaded	loadEmptyChassisCode	Represents if container is loaded or empty
steamshipBL		empty string
pickup_number		empty string
carrier.type		empty string
carrier.steamshipLine		empty string
carrier.vessel		empty string
carrier.voyage		empty string
destination.type		empty string
destination.site_id	destinationStateCode	Destination state code
destination.name	destinationStation333	Destination station name
event[n].code		One of the following values: ‘grounded’: when derivedEquipmentStatusName has “In Inv on Ground” or “On the Ground”, and equipmentLocationCode = “G” ‘arrived’: when derivedEquipmentStatusName has “In Inv on Ground” or “On the Ground”, and originstation333=destinationStation333 and current_state = destination_state ‘lfd’: when shipmentLastFreeStorageDate has value ‘released’: when shipmentLastFreeStorageDate has value ‘outgated’: when event code is ‘OG’ and event Date and event time has value ‘eta’: when EstimatedEquipmentUnloadDatetime has value and it is valid date ‘hold’: when derivedEquipmentStatusName contains “Storage” or “mechanical”
event[n].date		Date and time when this event was stored and it is value is always set to the current date time.
event[n]. location.site_id	equipmentLotRowSpotTierStatusName	The location site id
event[n]. location.name	EquipmentLotLocationName + equipmentLotRowLocationName + equipmentLotRowSpotLocationName	Name of the location
event[n].data.eta event[n].data.eta	EstimatedEquipmentUnloadDatetime	Date of the ETA event. Filled if the event_code = ‘eta’
event[n].data.outgated	eventDate, EventTime	Outgated event date. Filled if the event_code = ‘OG’
event[n].data.grounded	EstimatedEquipmentUnloadDatetime	Grounded event date. Filled if the event_code = ‘grounded’
event[n].data.arrived	EstimatedEquipmentUnloadDatetime	Arrival event date. Filled if the event_code = ‘arrived’
event[n].data.released	EstimatedEquipmentUnloadDatetime	Release event date. Filled if the event_code = ‘released’
event[n].data.hold_type		Contstant value ‘customs’

Internal Server Error Response

The server encountered an unexpected condition which prevented it from fulfilling the request. This is always a problem on the server side.

{
    "errors": [
        {
            "timestamp": "2021-10-22T11:42:49.17Z",
            "internalErrorId": "ib_customer_api_500",
            "httpStatusCode": 500,
            "message": "There was an internal error processing the request.",
            "messageLabel": "Internal Server Error"
        }
    ]
}

Bad Request Response

The request could not be understood by the server due to incorrect syntax.

{
    "errors": [
        {
            "timestamp": "2021-10-22T11:51:10.699Z",
            "internalErrorId": "ib_customer_api_400",
            "httpStatusCode": 400,
            "message": "Please submit a list of valid units",
            "messageLabel": "Bad Request"
        }
    ]
}

UnAuthorized request Response

Check the Authorization. Response is a plain text.

Access Denied

NotFound Response

The server cannot find the requested resource (URI). That is, the address of the endpoint in your request does not exist. Please consult the documentation.

Method Not Allowed Response

The request HTTP method is known by the server but has been disabled and cannot be used for that resource. For example, you may be using GET when POST is required. Please consult the documentation.

Too Many Requests Response

Bnsf Api has some limits, described above

Gateway Timeout Error Response

The server is acting as a gateway and cannot get a response in time for a request. Wait about one minute then try again

Todo

Was not able to get the response for NotFound, Method Not Allowed, Too many Requests and Gateway Timeout Error