openapi: 3.0.1
info:
  title: Data Services API
  description: "This document outlines instructions for retrieving various datasets from the eModal lakehouse for various ports and terminals. The data is made available via REST API calls for the following datasets:\r\n- Information about the available terminals for the port.\r\n- Appointment availability information in a specific terminal.\r\n- Aggregated container dwell statistics in a specific terminal.\r\n- Appointment performance metrics for a specific terminal."
  version: v1
servers:
  - url: /api
    description: Server
paths:
  /terminalmetrics/v{version}/terminals:
    get:
      tags:
        - TerminalMetrics
      summary: Retrieve Information About Terminals
      description: "This endpoint returns information about individual terminals including terminal name/code/ID, supported move types(pickup, drop off, etc.),\r\nand appointment type(slot vs pre-advice). This information is required to query specific terminal appointment availability or dwell statistics."
      operationId: Terminals
      parameters:
        - name: version
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: terminals retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TerminalMoveTypeModel'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Server error occured
      security:
        - apikey: []
  /terminalmetrics/v{version}/terminals/{terminal_id}/apptavailability:
    get:
      tags:
        - TerminalMetrics
      summary: Retrieve Metrics About Appointment Availability
      description: "This API endpoint returns appointment availability statistics for time slotted appointments. This API returns data only for the time slotted appointment move types and does not include pre-advice information\r\nas it is not applicable as an appointment availability statistic.\r\nThe response will contain appointment availability data starting with the current date and 7 days into the future and contain a listing of\r\navailable and booked appointments by move type and time slot for a specific terminal."
      operationId: terminals/{terminal_id}/apptavailability
      parameters:
        - name: terminal_id
          in: path
          description: >-
            The input is the terminal GUID received from the first API call and
            embed it along the URL to get the details of the specific terminal.
          required: true
          schema:
            type: string
            format: uuid
        - name: version
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: appointments by specific terminal ID retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TerminalMetricsModelDTOV2'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Server error occured
      security:
        - apikey: []
  /terminalmetrics/v{version}/terminals/{terminal_id}/containerdwelltime:
    get:
      tags:
        - TerminalMetrics
      summary: Retrieve Information About Terminal Dwell Statistics
      description: "This API endpoint provides information about container dwell time in a specific terminal. The dwelling time is calculated as an average dwell within the specified date range.\r\nDwell time is average time spent in hours on the terminal between containers discharge date and gate out date or from discharge to current dwell time on terminal."
      operationId: containerdwelltime
      parameters:
        - name: terminal_id
          in: path
          description: terminal GUID(terminal_id) retrieved from the terminal API call
          required: true
          schema:
            type: string
            format: uuid
        - name: start_date
          in: query
          description: >-
            Include all containers discharged after this date/time in dwell
            aggregation(Format: yyyy-MM-ddTHH:mm:ss)
          required: true
          schema:
            type: string
            format: date-time
        - name: end_date
          in: query
          description: >-
            Include all containers discharged prior to this date/time in dwell
            aggregation(Format: yyyy-MM-ddTHH:mm:ss)
          required: true
          schema:
            type: string
            format: date-time
        - name: dwell_option
          in: query
          description: "- on_terminal_only:\r\n  Retrieve dwell statistics only for containers which are on terminal.\r\n- off_terminal_only:\r\n  Retrieve dwell statistics only for containers that have already left the terminal.\r\n- all:\r\n  Retrieve dwell statistics for all containers that are in yard inventory as well as containers that have already left the terminal."
          required: true
          schema:
            type: string
        - name: trade_type
          in: query
          description: "- import:\r\n  Retrieve dwell statistics only for containers with import trade type.\r\n- export:\r\n  Retrieve dwell statistics only for containers with export trade type.\r\n\r\nIf trade type is empty, dwell statistics for all trade types (import and export) will be retrieved."
          schema:
            type: string
        - name: version
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Information about terminal dwell statistics retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContainerDwellTime'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Server error occured
      security:
        - apikey: []
  /terminalmetrics/v{version}/terminals/{terminal_id}/apptperformance:
    get:
      tags:
        - TerminalMetrics
      summary: >-
        Retrieves appointment performance metrics for a specific terminal within
        a given date range.
      description: "This endpoint returns aggregated appointment performance data for the specified terminal and date range.\r\nThe response includes appointment counts and related statistics."
      operationId: apptperformance
      parameters:
        - name: terminal_id
          in: path
          description: >-
            The unique identifier (GUID) of the terminal for which appointment
            performance is requested.
          required: true
          schema:
            type: string
            format: uuid
        - name: start_date
          in: query
          description: >-
            The start date of the range for which appointment performance is to
            be retrieved (format: yyyy-MM-dd).
          required: true
          schema:
            type: string
            format: date-time
        - name: end_date
          in: query
          description: >-
            The end date of the range for which appointment performance is to be
            retrieved (format: yyyy-MM-dd).
          required: true
          schema:
            type: string
            format: date-time
        - name: scac_cd
          in: query
          description: >-
            Optional. The Standard Carrier Alpha Code (SCAC) to filter
            appointments by carrier.
          schema:
            type: string
        - name: user_id
          in: query
          description: >-
            Optional. The unique identifier (GUID) of the user to filter
            appointments by user.
          schema:
            type: string
            format: uuid
        - name: version
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Appointment performance data retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Appointments'
        '400':
          description: Bad request, such as invalid terminal ID or date range.
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Server error occurred while processing the request.
      security:
        - apikey: []
components:
  schemas:
    AppointmentCounts:
      type: object
      properties:
        appointment_type:
          type: string
          nullable: true
        canceled:
          type: integer
          format: int64
        completed:
          type: integer
          format: int64
        missed:
          type: integer
          format: int64
        rescheduled:
          type: integer
          format: int64
        rebooked:
          type: integer
          format: int64
        inprogress:
          type: integer
          format: int64
        confimed:
          type: integer
          format: int64
        pending:
          type: integer
          format: int64
        error:
          type: integer
          format: int64
        trouble:
          type: integer
          format: int64
        feesDue:
          type: integer
          format: int64
        total:
          type: integer
          format: int64
      additionalProperties: false
    Appointments:
      type: object
      properties:
        date_aggregated_dttm:
          type: string
          format: date-time
        terminal_cd:
          type: string
          nullable: true
        terminal_name:
          type: string
          nullable: true
        terminal_id:
          type: string
          nullable: true
        scac_cd:
          type: string
          nullable: true
        user_id:
          type: string
          format: uuid
          nullable: true
        appointments:
          type: array
          items:
            $ref: '#/components/schemas/AppointmentCounts'
          nullable: true
        start_dttm:
          type: string
          nullable: true
        end_dttm:
          type: string
          nullable: true
      additionalProperties: false
    ContainerDwellTime:
      type: object
      properties:
        terminal_id:
          type: string
          description: >-
            The terminal ID refers to the unique identifier of the terminal for
            which the dwell time is being calculated.
          format: uuid
        start_dttm:
          type: string
          format: date-time
        end_dttm:
          type: string
          description: >-
            Include all containers discharged  prior to this date/time in dwell
            aggregation
          format: date-time
        container_count:
          type: integer
          description: Number of containers counted in dwell aggregation
          format: int32
        avg_dwell_time:
          type: number
          description: Average dwell time in hours
          format: double
        teu:
          type: number
          description: Total TEU of all containers matching search criteria
          format: double
        date_aggregated_dttm:
          type: string
          description: Date represents last modification date of records
          format: date-time
          nullable: true
      additionalProperties: false
    DataMetricsV2DTO:
      type: object
      properties:
        date_aggregated_dttm:
          type: string
          description: Request date and time in UTC time zone
          format: date-time
        date:
          type: string
          description: Appointment business date
          nullable: true
        move_type:
          type: array
          items:
            type: string
          description: "Appointment move type\r\nIP Import Container Pickup,\r\nMD Drop Empty Container, \r\nMP Pickup Empty Container,\r\nXD Drop Export Container, \r\nXP Pickup Dray (Export) Container, \r\nID Drop Dray (Import) Container, \r\nBD Drop Bare Chassis,\r\nBP Pickup Bare Chassis         ///"
          nullable: true
        move_type_desc:
          type: array
          items:
            type: string
          description: Full description of the move type
          nullable: true
        slot_desc:
          type: string
          description: Appointment time slot description
          nullable: true
        slot_start_dttm:
          type: string
          description: Appointment slot start date time
          format: date-time
        slot_end_dttm:
          type: string
          description: Appointment slot end date time
          format: date-time
        total_appointments:
          type: integer
          description: >-
            Total appointments made available by the terminal for this time slot
            and move type
          format: int32
        allocated_appointments:
          type: integer
          description: >-
            Number of appointments booked/consumed for this time slot and move
            type. This includes all the appointments in pending, confirmed, and
            completed statuses.
          format: int32
        blocked_flag:
          type: string
          description: An indicator if the time slot is blocked for future appointments.
          nullable: true
      additionalProperties: false
    TerminalMetricsModelDTOV2:
      type: object
      properties:
        appointments:
          type: array
          items:
            $ref: '#/components/schemas/DataMetricsV2DTO'
          nullable: true
      additionalProperties: false
    TerminalMoveTypeDetail:
      type: object
      properties:
        terminal_name:
          type: string
          description: Terminal official name
          nullable: true
          example: HUSKY
        terminal_cd:
          type: string
          description: Unique code assigned to the terminal
          nullable: true
        terminal_id:
          type: string
          description: Unique GUID identifier for the terminal
          nullable: true
        move_type:
          type: string
          description: "Appointment move type offered by the terminal (IP, MD, MP, XD, etc. Please refer to the table below.) \r\nIP Import Container Pickup,\r\nMD Drop Empty Container, \r\nMP Pickup Empty Container,\r\nXD Drop Export Container, \r\nXP Pickup Dray (Export) Container, \r\nID Drop Dray (Import) Container, \r\nBD Drop Bare Chassis,\r\nBP Pickup Bare Chassis"
          nullable: true
        appointment_type:
          type: string
          description: Appointment type set for above move type (slot vs preadvice)
          nullable: true
          example: slot
      additionalProperties: false
    TerminalMoveTypeModel:
      type: object
      properties:
        terminals:
          type: array
          items:
            $ref: '#/components/schemas/TerminalMoveTypeDetail'
          nullable: true
      additionalProperties: false
  securitySchemes:
    apikey:
      type: apiKey
      name: X-API-KEY
      in: header
