BNSF INTERMODAL API

openapi: 3.2.0
info:
  title: Bnsf INTERMODAL API
  description: ''
  termsOfService: http://www.bnsf.com/site-terms-of-use.html
  contact:
    name: BNSF Customer API
    email: CustomerAPI@bnsf.com
  version: '1.0'
servers:
- url: https://api.bnsf.com:6443
tags:
- name: Intermodal
paths:
  /v1/trip-plan-intermodal:
    get:
      tags:
      - Intermodal
      summary: Trip Plan - Returns list of significant events planned for an intermodal…
      parameters:
      - name: equipmentInitial
        in: query
        description: Equipment Initial.
        schema:
          type: string
          example: BNSF
      - name: equipmentNumber
        in: query
        description: Equipment Number.
        schema:
          type: string
          example: '12345'
      responses:
        '200':
          description: '**OK**


            The request has succeeded.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tripPlan'
        '400':
          $ref: '#/components/responses/400'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '405':
          $ref: '#/components/responses/405'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
        '504':
          $ref: '#/components/responses/504'
      operationId: getV1TripPlanIntermodal
      x-operation-id-source: derived
  /v1/units:
    get:
      tags:
      - Intermodal
      summary: Units - Returns tracing details for units on the BNSF network, with a default…
      description: 'Changelog

        - July 2026: Added tofccofc field in response'
      parameters:
      - name: limit
        in: query
        description: The default and maximum number of intermodal units to return per request.
        schema:
          type: integer
          format: int32
          example: 2000
      - name: page
        in: query
        description: The page number of the set of intermodal units you are requesting. For example, a query string of "?page=1" is equivalent to "?page=1&limit=2000" will return the first 2,000 units. "?page=2" will return the next set of 2,000 units.
        schema:
          type: integer
          format: int32
          example: 1
      responses:
        '200':
          description: '**OK**


            The request has succeeded.'
          content:
            application/json:
              schema:
                type: object
                title: Schema
                properties:
                  elements:
                    type: array
                    title: elements
                    items:
                      $ref: '#/components/schemas/intermodal'
                additionalProperties: false
        '400':
          $ref: '#/components/responses/400'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '405':
          $ref: '#/components/responses/405'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
        '504':
          $ref: '#/components/responses/504'
      operationId: getV1Units
      x-operation-id-source: derived
    post:
      tags:
      - Intermodal
      summary: Units - Returns tracing details for requested units, up to 300 at a time
      description: 'Changelog

        - July 2026: Added tofccofc field in response'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                unitList:
                  $ref: '#/components/schemas/equipment_list'
              additionalProperties: false
      responses:
        '200':
          description: '**OK**


            The request has succeeded.'
          content:
            application/json:
              schema:
                type: object
                title: Schema
                properties:
                  elements:
                    type: array
                    title: Elements
                    items:
                      $ref: '#/components/schemas/intermodal'
                additionalProperties: false
        '400':
          $ref: '#/components/responses/400'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '405':
          $ref: '#/components/responses/405'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
        '504':
          $ref: '#/components/responses/504'
      operationId: postV1Units
      x-operation-id-source: derived
components:
  schemas:
    equipment_list:
      type: array
      title: Equipment List
      items:
        type: string
        example: BNSF123456
      minItems: 1
      maxItems: 300
      example:
      - BNSF123456
      - BNSF301133
    tripPlan:
      type: object
      title: Trip Plan
      description: Travel itinerary for rail equipment.
      properties:
        jobStatus:
          type: integer
          format: int32
          title: jobStatus
          minimum: 1
          maximum: 4
          example: 4
        jobStatusDescription:
          type: string
          title: jobStatusDescription
          example: Job is complete
        resultSet:
          type: array
          title: resultSet
          items:
            type: object
            required:
            - equipmentInitial
            - equipmentNumber
            - estimatedEventDatetimeIndicator
            - eventDatetime
            - eventDescription
            - eventLocation
            - sequenceNumber
            - trainId
            properties:
              equipmentInitial:
                type: string
                title: Equipment Initial
                description: Equipment Initial is the prefix or alphabetic part of an equipment units identifying number.
                example: BNSF
              equipmentNumber:
                type: string
                title: Equipment Number
                description: Equipment Number is the sequencing or serial part of an equipment units identifying number.
                example: '12345'
              estimatedEventDatetimeIndicator:
                type: string
                title: Estimated Event DateTime Indicator
                description: Indicates if the Event DateTime is estimated or actual.
                example: Y
              eventDatetime:
                type: string
                title: Event DateTime
                description: Date and Time when a given event was created. This represents the complete Date (YYYY-MM-DD), on the Gregorian calendar, along with a valid complete Time (HH:MM:SS:xx)
                example: 2021-11-17 15.47.51
              eventDescription:
                type: string
                title: Event Description
                description: Description for an Event Code used to define an event or activity occurring on the rail network.
                example: Train Departure
              eventLocation:
                type: string
                title: Event Location Name
                description: The combined name of the City and State Code where the event will or has occurred.
                example: CLOVIS NM
              sequenceNumber:
                type: number
                format: float
                title: Trip Plan Segment Sequence Number
                description: The sequence number applied to the processing (occurrence) of equipment through individual trip plan segments.
                example: 110
              trainId:
                type: string
                title: Train ID
                description: The identification of an train.
                example: S MEMSCO 1 15
            additionalProperties: false
        rowCount:
          type: string
          title: rowCount
          example: '1'
      additionalProperties: false
    intermodal:
      type: object
      title: Intermodal
      properties:
        bnsfTransitGoalDate:
          type: string
          title: bnsfTransitGoalDate
          description: 'BNSF transit goal date

            '
          example: 10/31/2019
        bnsfTransitGoalTime:
          type: string
          title: bnsfTransitGoalTime
          description: 'BNSF transit goal time

            '
          example: 04:00
        carId:
          type: string
          title: carId
          description: 'The car initial and number used to move the intermodal unit or VIN

            '
          example: BNSF255011
        chassisId:
          type: string
          title: chassisId
          description: The chassis identification number used for the shipment
        confirmedEstimatedCustomerNotificationDate:
          type: string
          title: confirmedEstimatedCustomerNotificationDate
          description: The confirmed estimated date that the customer will be notified of delivery
          example: 10/31/2019
        confirmedEstimatedCustomerNotificationTime:
          type: string
          title: confirmedEstimatedCustomerNotificationTime
          description: The confirmed estimated time that the customer will be notified of delivery
          example: 01:00
        customerRequestedDate:
          type: string
          title: customerRequestedDate
          description: 'Date of the customer request for shipment availability

            '
          example: 10/31/2019
        customerRequestedTime:
          type: string
          title: customerRequestedTime
          description: 'Time of the customer request for shipment availability

            '
          example: 04:00
        demurrageAmount:
          type: number
          format: double
          title: demurrageAmount
          description: 'The amount charged for storage if not picked up (USD)

            '
          example: 0
        demurrageStartDate:
          type: string
          title: demurrageStartDate
          description: The latest date the shipment will be held for storage if not picked up
          example: 01/03/2020
        destinationRailNetworkLocationName:
          type: string
          title: destinationRailNetworkLocationName
          description: 'The final BNSF operating station and state. This can be different than customer destination. See **finalDestinationRailNetworkLocationName** the final rail station and state as stated on the waybill.  '
          example: ALLIANCE, TX
        equipmentInitial:
          type: string
          title: equipmentInitial
          description: The initials used in the equipment identification for the shipment.
          example: BNFZ
        equipmentNumber:
          type: string
          title: equipmentNumber
          description: The numbers used in  the equipment identification for the shipment.
          example: '103071'
        estimatedShipmentAvailabilityDate:
          type: string
          title: estimatedShipmentAvailabilityDate
          description: 'Estimated date that the shipment becomes available to the customer

            '
          example: 10/31/2019
        estimatedShipmentAvailabilityTime:
          type: string
          title: estimatedShipmentAvailabilityTime
          description: 'Estimated time that the shipment becomes available to the customer

            '
          example: 01:24
        estimatedCustomerNotificationDate:
          type: string
          title: estimatedCustomerNotificationDate
          description: The estimated date that the customer will be notified of delivery
          example: 10/31/2019
        estimatedCustomerNotificationTime:
          type: string
          title: estimatedCustomerNotificationTime
          description: The estimated time that the customer will be notified of delivery
          example: 01:00
        finalDestinationRailNetworkLocationName:
          type: string
          title: finalDestinationRailNetworkLocationName
          description: The final station and state as stated on the waybill.
          example: ALLIANCE, TX
        finalScheduledEventDescription:
          type: string
          title: finalScheduledEventDescription
          description: Description of the final scheduled event in the trip plan
          example: Deramp
        lastEventDate:
          type: string
          title: lastEventDate
          description: Date of most recent event.
          example: 10/30/2019
        lastEventDescription:
          type: string
          title: lastEventDescription
          description: 'Description of most recent event

            '
          example: Passing
        lastEventTime:
          type: string
          title: lastEventTime
          description: Time of most recent event.
          example: 615
        lastEventRailNetworkLocationName:
          type: string
          title: lastEventRailNetworkLocationName
          description: The location of the most recently reported event. See Event Description.
          example: REDROCK, OK
        lastReportingSCAC:
          type: string
          title: lastReportingSCAC
          description: Carrier abbreviation reporting the most recent event.
          example: BNSF
        latitude:
          type: number
          format: float
          title: Latitude
          description: Last reported latitude of the shipment.
          example: 37.260433
        longitude:
          type: number
          format: float
          title: Longitude
          description: Last reported longitude of the shipment.
          example: -97.60999
        lotRowSpotLabel:
          type: string
          title: lotRowSpotLabel
          description: 'This is the is the lot, row and spot where the intermodal unit is placed for pickup by the trucker. Also called Lot Location.

            '
        message:
          type: string
          title: Message
          description: Message regarding equipment search
          example: You are not an authorized waybill party to track this equipment. Please verify your information and try again.
        nextSCAC:
          type: string
          title: nextSCAC
          description: The next carrier to move the shipment after BNSF.
          example: UP
        nextScheduledEventDate:
          type: string
          title: nextScheduledEventDate
          description: The estimated date the next scheduled event will occur.
          example: 10/30/2019
        nextScheduledEventDescription:
          type: string
          title: nextScheduledEventDescription
          description: The next scheduled event to occur in the trip plan.
          example: Train Departed
        nextScheduledEventStateCode:
          type: string
          title: nextScheduledEventStateCode
          description: The state where the next scheduled event will occur.
          example: OK
        nextScheduledEventStation333:
          type: string
          title: nextScheduledEventStation333
          description: The station where the next scheduled event will occur.
          example: OKLCITY
        nextScheduledEventTime:
          type: string
          title: nextScheduledEventTime
          description: The estimated time the next scheduled event will occur.
          example: 774
        originRailNetworkLocationName:
          type: string
          title: originRailNetworkLocationName
          description: The origin station and state of the shipment.
          example: STPAUL, MN
        originalTrainDepartureDate:
          type: string
          title: originalTrainDepartureDate
          description: Original train departure date
          example: 10/29/2019
        originalTrainDepartureTime:
          type: string
          title: originalTrainDepartureTime
          description: Original train departure time
          example: 965
        originalTrainDepartureTypeCode:
          type: string
          title: originalTrainDepartureTypeCode
          description: Original train departure type code.
          example: A
        shipmentExceptionDescription:
          type: string
          title: shipmentExceptionDescription
          description: 'A description of any exception that applies to the shipment

            '
          example: WILD DETECTOR/ WHL CONDITION
        trainId:
          type: string
          title: trainId
          description: 'The code that identifies a specific train and is used to locate cars, units, or shipments. Train IDs consist of four parts:


            Type: Train type, based on the commodity being transported, or the speed the train needs to move. Valid values range from A to Z.

            Symbol: A combination of carrier interchange and the number of trains out that day.

            Day: The day of the month the train departed from origin location, in mm-dd format.

            Schedule ID: A value from A to Z.

            '
          example: ZWSPALT127A
        truckingCompanyName:
          type: string
          title: truckingCompanyName
          description: The assigned trucker to move the shipment
          example: ABC
        unitTypeCode:
          type: string
          title: unitTypeCode
          description: This is a code that identifies the type of equipment used for the shipment
          example: POG
        waybillNumber:
          type: string
          title: waybillNumber
          description: Waybill number assigned to the shipment.
          example: '654321'
        careOfParty633:
          type: string
          title: careOfParty633
          description: Name of a receiver of rail cars on behalf of the actual consignee (the  physical delivery point) which has been abbreviated from the Customer's full Legal Name through the use of a standardized programmatic process.
          example: CAREOF1
        careOfPartyFullName:
          type: string
          title: careOfPartyFullName
          description: The full name of a  receiver of rail cars on behalf of the actual consignee (the  physical delivery point).
          example: CARE OF 1
        consignee633:
          type: string
          title: consignee633
          description: Name of a Customer, acting as the Consignee (AKA Receiver), which has been abbreviated from the Customer's full Legal Name through the use of a standardized programmatic process.
          example: CNSGNEE
        consigneeFullName:
          type: string
          title: consigneeFullName
          description: The full name of a customer that is filling the role of Consignee. A Consignee, also referred to as the \"Receiver\", is the company or individual receiving a shipment at a destination.
          example: CONSIGNEE
        notifyParty633:
          type: string
          title: notifyParty633
          description: Name of the party to be notified at the time a container or trailer is grounded from a train. Most notify parties are draymen. Value has been abbreviated from the Customer's full Legal Name through the use of a standardized programmatic process.
          example: NOTPRTY1
        notifyPartyFullName:
          type: string
          title: notifyPartyFullName
          description: Full name of the party to be notified at the time a container or trailer is grounded from a train. Most notify parties are draymen.
          example: NOTIFY PARTY 1
        shipper633:
          type: string
          title: shipper633
          description: Name of a Customer, acting as the Shipper, which has been abbreviated from the Customer's full Legal Name through the use of a standardized programmatic process.
          example: SHPRABC
        shipperFullName:
          type: string
          title: shipperFullName
          description: Full name of a Customer, acting as the Shipper.
          example: SHIPPER
        stcc:
          type: string
          title: stcc
          description: STCC (Standard Transportation Commodity Code) number identifying a Commodity.
          example: '9999'
        bol:
          type: string
          title: bol
          description: Is a unique identifier for an instance of an internal or external customer request for the Bill of Lading via rail.
          example: 017415FD
        tofccofc:
          type: string
          title: tofccofc
          description: TOFC = Trailer on Flat Car, COFC = Container on Flat Car
          example: C
      additionalProperties: false
  responses:
    '429':
      description: "**Too Many Requests**\n\nThe BNSF API Gateway enforces rate limits to maintain application security and performance.  Current rate limits are set as follows:\n* 1 API Request Per Second, Per Partner, Per Service\n* 15 API Requests Per Minute, Per Partner, Per Service\n* 100 API Request Per Minute, Per Service\n \nWhen requests exceed these limits the API Gateway will return a **429 Too Many Requests** error response. Upon receiving such exceptions, you can resubmit failed requests in a rate-limited manner, complying with the API Gateway throttle limits. "
    '404':
      description: '**Not Found**


        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.'
    '403':
      description: "Unauthorized request. Here are the most common causes:\n    \n* You are getting 403 Access Denied.\n\n   * It takes a few days for us to get you set up after you register. When set up is complete, you will receive an email letting you know. If you have not received the email, please wait up to five business days. Let us know via API Support if you still have not received the email after five business days.\n   * You can also get this error if your certificate is not configured properly on your side. Please review the Mutual Authentication in the Getting Started section of our documentation. \n\n\n* You are getting 403 \"message\": \"Insufficient privileges\" when accessing a restricted service for which you do not have permission. You can use our Registration form to request access. Be sure to explain the situation in the \"Please explain how you intend to use the API\" field.\n"
    '400':
      description: '**Bad Request**


        The request could not be understood by the server due to incorrect syntax. Do not repeat the request without modifications.'
    '504':
      description: '**Gateway Timeout**


        The server is acting as a gateway and cannot get a response in time for a request. Wait about one minute then try again.'
    '500':
      description: '**Internal Server Error**


        The server encountered an unexpected condition which prevented it from fulfilling the request. This is always a problem on the server side. Our internal support systems will be made aware.'
    '405':
      description: '**Method Not Allowed**


        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.'