openapi: 3.1.0
info:
  title: Maersk Air Booking AirBookings Tracking API
  description: 'Submit air freight booking requests via Maersk Air Cargo. Covers consolidation, charter, and forwarder bookings between supported origin and destination airports.

    '
  version: '1.0'
  contact:
    name: Maersk Developer Support
    url: https://developer.maersk.com/support
servers:
- url: https://api.maersk.com
  description: Production Gateway
security:
- ConsumerKey: []
tags:
- name: Tracking
  description: Container and shipment tracking events.
paths:
  /track-and-trace-private/shipments:
    get:
      summary: List Shipment Tracking Events
      description: 'Retrieve neutralized tracking events for a shipment referenced by container number, bill-of-lading number, or booking number. Returns location, vessel, voyage, planned and actual timestamps for each milestone.

        '
      operationId: listShipmentEvents
      tags:
      - Tracking
      parameters:
      - name: equipmentReference
        in: query
        description: Container number (ISO 6346).
        schema:
          type: string
          example: MSKU1234567
      - name: transportDocumentReference
        in: query
        description: Bill of lading number.
        schema:
          type: string
          example: 909876543
      - name: carrierBookingReference
        in: query
        description: Booking reference number.
        schema:
          type: string
          example: 222334455
      - name: Consumer-Key
        in: header
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Tracking events returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShipmentTracking'
        '401':
          description: Unauthorized — invalid or missing API key.
        '404':
          description: Reference not found.
        '429':
          description: Rate limit exceeded.
  /track-and-trace-private/events:
    get:
      summary: List Container Events
      description: 'Retrieve fine-grained event stream for a single container, including transport events, equipment events, and shipment events.

        '
      operationId: listContainerEvents
      tags:
      - Tracking
      parameters:
      - name: equipmentReference
        in: query
        required: true
        schema:
          type: string
      - name: eventType
        in: query
        description: TRANSPORT, EQUIPMENT, or SHIPMENT.
        schema:
          type: string
          enum:
          - TRANSPORT
          - EQUIPMENT
          - SHIPMENT
      - name: limit
        in: query
        schema:
          type: integer
          default: 100
      - name: Consumer-Key
        in: header
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Container events returned.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Event'
        '401':
          description: Unauthorized.
        '404':
          description: Container not found.
components:
  schemas:
    Event:
      type: object
      properties:
        eventID:
          type: string
        eventType:
          type: string
          enum:
          - TRANSPORT
          - EQUIPMENT
          - SHIPMENT
        eventClassifierCode:
          type: string
          enum:
          - PLN
          - ACT
          - EST
          description: Planned, Actual, or Estimated.
        eventDateTime:
          type: string
          format: date-time
        location:
          $ref: '#/components/schemas/Location'
        transportCall:
          $ref: '#/components/schemas/TransportCall'
        equipmentReference:
          type: string
    ShipmentTracking:
      type: object
      properties:
        carrierBookingReference:
          type: string
        transportDocumentReference:
          type: string
        events:
          type: array
          items:
            $ref: '#/components/schemas/Event'
    Location:
      type: object
      properties:
        locationName:
          type: string
        UNLocationCode:
          type: string
          description: UN/LOCODE for the port or facility.
        countryCode:
          type: string
    TransportCall:
      type: object
      properties:
        carrierServiceCode:
          type: string
        vesselIMONumber:
          type: string
        carrierVoyageNumber:
          type: string
        modeOfTransport:
          type: string
          enum:
          - VESSEL
          - RAIL
          - TRUCK
          - BARGE
          - MULTIMODAL
  securitySchemes:
    ConsumerKey:
      type: apiKey
      in: header
      name: Consumer-Key