openapi: "3.0.0"
info:
  version: 1.0.1
  title: APMT Track and Trace - Vessel Visits
  description: APMT Track and Trace - Vessel Visits API
  termsOfService: https://developer.apmterminals.com/terms
  contact:
    name: APM Terminals API Management Team
    email: api@apmterminals.com
    url: https://developer.apmterminals.com
servers:
  - url: https://api.apmterminals.com/
    description: Production API
  - url: https://api-sandbox.apmterminals.com/
    description: Sandbox API
paths:
  /vessel-visits:
    get:
      description: Returns Vessel Visits by voyage numbers
      operationId: getVesselVisits
      parameters:
        - in: query
          schema: 
            type: string
          name: assetId
          description: Either the vessel name or vessel lloyds code.
          required: true
        - in: query
          schema:
            type: string
            pattern: '^[A-Z]{3}$'
          name: facilityCode
          description: The Terminal UN Location Code to search for (USLAX for Los Angeles etc). Only accepts a single Terminal Code. Possible values are USLAX (Los Angeles, US), USMOB (Mobile, US), USNWK (Port Elizabeth, US), SEGOT (Gothenburg, Sweden), ITVDL (Vado, Italy) NGAPP (Apapa, Nigeria), BHKBS (Bahrain), USMIA (Miami, US) and ARBUE (Buenos Aires, Argentina).
          required: true
        - in: query
          schema:
            type: string
          name: inboundVoyageNumber
          description: The master inbound vessel voyage number.
          required: false
        - in: query
          schema:
            type: string
          name: outboundVoyageNumber
          description: The master outbound vessel voyage number.
          required: false
      responses:
        '200':
          description: Successfully returned import availability data.
          content:
            application/json:
              schema:
                #type: array
                #items:
                  $ref: '#/components/schemas/VesselVisits'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: The user is not authenticated in the system
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: The user does not have permissions to access this endpoint
          content:
            application/json:
              schema:          
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Bad URL.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        #default:
        #  description: Sorry, an error has occured.
        #  content:
        #    application/json:
        #      schema:
        #        $ref: '#/components/schemas/ApiError'
components:
  #securitySchemes:
  #  oAuth2:
  #    type: oauth2
  #    description: This API uses OAuth 2 with the implicit grant flow. [More info](https://api.example.com/docs/auth)
  #    flows:
  #      clientCredentials:
  #        tokenUrl: ""
  #        scopes: {}
  schemas:
    VesselVisits:
      type: object
      properties:
        vesselName:
          description: Name of vessel queried.
          type: string
          example: 'MAERSK ENPING'
        vesselLloydsCode:
          description: Lloyds code of vessel queried.
          type: string
          example: '9383259'
        inboundVoyageNumber:
          description: The inbound voyage number for the vessel queried.
          type: string
          example: 015N
        outboundVoyageNumber:
          description: The outbound voyage number for the vessel queried.
          type: string
          example: 017S
        scheduledEtaDateTimeLocal:
          description: Date and local time with UTC offset, where the vessel was initially scheduled to arrive at the facility.
          type: string
          format: date-time
          example: '2020-04-25T08:00:00-07:00'
        latestEtaDateTimeLocal:
          description: Updated date and local time with UTC offset, where the vessel is scheduled to arrive at the facility.
          type: string
          format: date-time
          example: '2020-04-25T08:00:00-07:00'
        actualEtaDateTimeLocal:
          description: Date and local time with UTC offset, where vessel actually arrived at the facility.
          type: string
          format: date-time
          example: '2019-12-06T00:00:00-07:00'
        scheduledEtdDateTimeLocal:
          description: Date and local time with UTC offset, where the vessel was initially scheduled to depart from the facility.
          type: string
          format: date-time
          example: '2020-04-25T17:00:00-07:00'
        latestEtdDateTimeLocal:
          description: Updated date and local time with UTC offset, where the vessel is scheduled to depart from the facility.
          type: string
          format: date-time
          example: '2020-04-25T17:00:00-07:00'
        actualEtdDateTimeLocal:
          description: Date and local time with UTC offset, where the vessel actually departed from the facility.
          type: string
          format: date-time
          example: '2019-12-06T00:00:00-07:00'
        cargoCutOffDateTimeLocal:
          description: Date and local time with UTC offset, where cargo will not be accepted for the vessel/voyage queried.
          type: string
          format: date-time
          example: '2020-04-25T17:00:00-07:00'
        reeferCutOffDateTimeLocal:
          description: Date and local time with UTC offset, where reefer cargo will not be accepted for the vessel/voyage queried.
          type: string
          format: date-time
          example: '2019-12-06T00:00:00-07:00'
        berthName:
          description: The physical Berth the ship is docked at 
          type: string
          example: 'B1'
        shippingLines:
          description: String list of all shipping lines on the vessel queried.
          type: string
          example : 'APL,CMA,MAE,SAF,SEA,SUD,UNK'
        vesselStatus:
          description: The current vessel status as known by the facility.
          type: string
          example: 'CREATED'
        terminalDateTimeLocalStamp:
          description: Time stamp of the facilities date and local time with UTC offset, when query was processed.
          type: string
          format: date-time
          example: '2020-04-23T10:35:02.307-07:00'
    ApiError:
      type: object
      required:
      - method
      - requestUri
      - status
      - timestamp
      - message
      - debugMessage
      properties:
        method:
          type: string
          description: The request method type
          example: GET
        requestUri:
          type: string
          description: The request URI.
        status:
          type: string
          description: The textual representation of the response status.
          example: OK
        timestamp:
          type: string
          format: date-time
          description: The date and time the error occured.
        message:
          type: string
          description: High level error message.
        debugMessage:
          type: string
          description: Detailed error message.
        subErrors:
          type: array
          items:
            $ref: '#/components/schemas/ApiValidationError'
          description: The list of invalid fields in the request.
    ApiValidationError:
      type: object
      required:
      - field
      - rejectedValue
      - message
      properties:
        field:
          type: string
          description: The field that has failed validation.
        rejectedValue:
          type: string
          description: The value that has failed validation.
        message:
          type: string
          description: The reason and advice for failed validation.          
  securitySchemes:
    oauth2:
      type: oauth2
      description: APMT IAM OAuth 2.0 with client credentials only.
      flows:
        clientCredentials:
          tokenUrl: https://api.apmterminals.com/oauth/client_credential/accesstoken?grant_type=client_credentials
          scopes:
            client_write: Write data