openapi: 3.0.3
info:
  title: Union Pacific Account Shipment API
  version: '1.0'
  description: The Union Pacific API provides developers and businesses with programmatic access to real-time railroad supply chain data and operational actions. The API enables shipment tracking, equipment management, order placement, case management, and intermodal planning. APIs are structured as data objects (building blocks) that can be used standalone or combined to create more robust supply chain workflows. Authentication uses OAuth 2.0 token-based flow with Client Credentials.
  contact:
    name: Union Pacific API Support
    email: apisupport@up.com
  x-generated-from: documentation
  x-last-validated: '2026-05-03'
servers:
- url: https://api.up.com
  description: Union Pacific API
security:
- oauth2: []
tags:
- name: Shipment
  description: Track and manage rail shipments with location and ETA data
paths:
  /shipment:
    get:
      operationId: listShipments
      summary: List Shipments
      description: Search active shipments to view ETA and current location information. Returns shipments matching the provided filters.
      tags:
      - Shipment
      parameters:
      - name: shipmentId
        in: query
        required: false
        description: Filter by shipment identifier
        schema:
          type: string
      - name: equipmentNumber
        in: query
        required: false
        description: Filter by equipment (rail car) number
        schema:
          type: string
      - name: origin
        in: query
        required: false
        description: Origin location code
        schema:
          type: string
      - name: destination
        in: query
        required: false
        description: Destination location code
        schema:
          type: string
      - name: accountId
        in: query
        required: false
        description: Account identifier to filter shipments
        schema:
          type: string
      responses:
        '200':
          description: List of matching shipments
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Shipment'
        '401':
          description: Unauthorized — invalid or expired OAuth token
        '403':
          description: Forbidden — insufficient permissions
  /shipment/{shipmentId}:
    get:
      operationId: getShipment
      summary: Get Shipment
      description: Retrieve details for a specific shipment including current location and ETA.
      tags:
      - Shipment
      parameters:
      - name: shipmentId
        in: path
        required: true
        description: Unique shipment identifier
        schema:
          type: string
      responses:
        '200':
          description: Shipment details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Shipment'
        '401':
          description: Unauthorized
        '404':
          description: Shipment not found
components:
  schemas:
    Location:
      type: object
      description: A Union Pacific network facility or location
      properties:
        locationCode:
          type: string
          description: Location identifier code
        name:
          type: string
          description: Location name
        type:
          type: string
          description: Location type (TERMINAL, YARD, INTERMODAL, STATION)
        city:
          type: string
          description: City
        state:
          type: string
          description: US state code
        latitude:
          type: number
          format: double
          description: Geographic latitude
        longitude:
          type: number
          format: double
          description: Geographic longitude
    Shipment:
      type: object
      description: A rail shipment with tracking and ETA information
      properties:
        shipmentId:
          type: string
          description: Unique shipment identifier
        status:
          type: string
          description: Current shipment status
          enum:
          - IN_TRANSIT
          - DELIVERED
          - DELAYED
          - HELD
          - CANCELLED
        origin:
          type: string
          description: Origin location code
        destination:
          type: string
          description: Destination location code
        currentLocation:
          $ref: '#/components/schemas/Location'
        estimatedArrival:
          type: string
          format: date-time
          description: Estimated time of arrival at destination
        estimatedGate:
          type: string
          format: date-time
          description: Estimated gate time at destination
        equipment:
          type: array
          items:
            $ref: '#/components/schemas/Equipment'
          description: Equipment associated with this shipment
        accountId:
          type: string
          description: Account identifier
        waybillNumber:
          type: string
          description: Associated waybill number
        commodity:
          type: string
          description: Type of commodity being shipped
    Equipment:
      type: object
      description: Rail equipment (car) with specifications and tracking status
      properties:
        equipmentNumber:
          type: string
          description: Equipment identifier (rail car number)
        type:
          type: string
          description: Equipment type (e.g., BOXCAR, FLATCAR, TANK_CAR, INTERMODAL)
        status:
          type: string
          description: Current equipment status
        currentLocation:
          type: string
          description: Current location code
        specifications:
          type: object
          description: Equipment specifications (length, capacity, etc.)
          properties:
            length:
              type: number
              description: Length in feet
            capacity:
              type: number
              description: Capacity in tons