CS_v1.0.3.yaml

openapi: 3.0.3
info:
  title: DCSA OpenAPI specification for Commercial Schedules
  version: 1.0.3
  description: |
    API specification issued by [Digital Container Shipping Association (DCSA)](https://dcsa.org/).

    The Commercial Schedules API offers BCOs, LSPs, and Solution Platforms three different methods and endpoints to access schedules from carriers based on their specific needs: Point-to-Point Routings, Port Schedules, and Vessel Schedules. 

    **Commercial schedules - point-to-point routings**: provides the product offering of single or multiple estimated end-to-end route options for a shipment in the pre-booking phase. This includes point-to-point specification of all transport legs, estimated timings, estimated schedules and interdependencies between transport legs.
     
    **Commercial schedules - port schedules**: provides, for a required specific port and starting date, the set of all vessels arriving and departing from the port with the corresponding estimated timestamps.
     
    **Commercial schedules - vessel schedules**: provides, for a required specific service and/or voyage and/or vessel and/or location, the timetable of estimated departure and arrival times for each port call on the rotation of the vessel(s).

    **All use cases mentioned in this API specification refer to use cases defined in the Commercial Schedules Interface Standard.**

    The Commercial Schedules endpoints can be implemented independently:

    `1. GET /v1/point-to-point-routes # For Point to Point Routings`

    `2. GET /v1/port-schedules # For Port Schedules`

    `3. GET /v1/vessel-schedules # For Vessel Schedules`

    Visit the [DCSA Website](https://dcsa.org/standards/commercial-schedules/) to find other documentation related to the standard publication (i.e. Interface Standard, Information Model).

    ### API Design & Implementation Principles
    This API follows the guidelines defined in version 2.0 of the API Design & Implementation Principles which can be found on the [DCSA Developer page](https://developer.dcsa.org/api_design).

    For a changelog please click [here](https://github.com/dcsaorg/DCSA-OpenAPI/tree/master/cs/v1#v103). If you have any questions, feel free to [Contact Us](https://dcsa.org/get-involved/contact-us).
  license:
    url: 'https://www.apache.org/licenses/LICENSE-2.0.html'
    name: Apache 2.0
  contact:
    name: Digital Container Shipping Association (DCSA)
    url: 'https://dcsa.org/'
    email: info@dcsa.org
paths:
  /v1/point-to-point-routes:
    get:
      summary: Point to Point Routing
      tags:
        - Point To Point
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PointToPoint'
          headers:
            API-Version:
              schema:
                type: string
                example: 1.0.2
              description: |
                SemVer used to indicate the version of the contract (API version) returned.
            Next-Page-Cursor:
              schema:
                type: string
                maxLength: 1024
                example: fE9mZnNldHw9MTAmbGltaXQ9MTA
              description: |
                The `Next-Page-Cursor` header contains a cursor value that points to the next page of results in a paginated API response.
                When an initial `GET` endpoint request includes the query parameter `limit=...` the API provider limits the number of items in the root array of the response to the specified limit. If the response would contain more items than the specified limit, the API provider includes only the first set of limit items and appends the following response header:
                `Next-Page-Cursor=fE9mZnNldHw9MTAmbGltaXQ9MTA`, a string that acts as a reference for the next page of results. The `Next-Page-Cursor` value is used in a subsequent request to retrieve the next page by passing it as a value in the `cursor`-query parameter: `cursor=fE9mZnNldHw9MTAmbGltaXQ9MTA`.

                To retrieve the next page, the API consumer sends a `GET` request to the endpoint URL with `cursor=fE9mZnNldHw9MTAmbGltaXQ9MTA` as query parameter along with the limit of items per page and any other query parameters used in the original request. Filter parameters may not be altered and MUST be preserved when requesting subsequent pages.
        '400':
          description: Bad Request
          headers:
            API-Version:
              schema:
                type: string
                example: 1.0.2
              description: |
                SemVer used to indicate the version of the contract (API version) returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Example 1:
                  value:
                    httpMethod: GET
                    requestUri: 'https://dcsa.org/cs/v1/point-to-point'
                    statusCode: 400
                    statusCodeText: Bad Request
                    providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962
                    errorDateTime: '2019-11-12T07:41:00+08:30'
                    errors:
                      - errorCode: 7005
                        property: placeOfDelivery
                        value: SG
                        errorCodeText: invalidQuery
                        errorCodeMessage: PlaceOfDelivery does not exist
        '500':
          description: Internal Server Error
          headers:
            API-Version:
              schema:
                type: string
                example: 1.0.2
              description: |
                SemVer used to indicate the version of the contract (API version) returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Example 1:
                  value:
                    httpMethod: GET
                    requestUri: 'https://dcsa.org/cs/v1/point-to-point'
                    statusCode: 500
                    statusCodeText: Internal Server Error
                    statusCodeMessage: Unable to process request
                    providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962
                    errorDateTime: '2019-11-12T07:41:00+08:30'
                    errors:
                      - errorCode: 7007
                        property: UNLocationCode
                        value: NA
                        errorCodeText: invalidQuery
                        errorCodeMessage: UNLocationCode does not exist
      operationId: get-v1-point-to-point
      parameters:
        - schema:
            type: string
            pattern: ^[A-Z]{2}[A-Z2-9]{3}$
            minLength: 5
            maxLength: 5
            example: NLAMS
          in: query
          name: placeOfReceipt
          description: The `UNLocationCode` specifying where the place is located.
          required: true
        - schema:
            type: string
            pattern: ^[A-Z]{2}[A-Z2-9]{3}$
            minLength: 5
            maxLength: 5
            example: NLAMS
          in: query
          name: placeOfDelivery
          description: The `UNLocationCode` specifying where the place is located.
          required: true
        - schema:
            type: string
            format: date
            example: '2021-04-01'
          in: query
          name: departureStartDate
          description: |
            Limit the result based on the earliest departureDate. 
            - If provided without departureEndDate, returns all routings with departures from the specified departureStartDate onwards.
            - If provided with departureEndDate, returns all routings with departures within the specified date range, inclusive of both dates.
            - If the same date is provided for both departureStartDate and departureEndDate, returns all routings with departures on that specific date.
        - schema:
            type: string
            format: date
            example: '2021-05-01'
          in: query
          name: departureEndDate
          description: |
            Limit the result based on the latest departureDate. 
            - If provided without departureStartDate, returns all routings with departures up to the specified departureEndDate.
            - If provided with departureStartDate, returns all routings with departures within the specified date range, inclusive of both dates.
            - If the same date is provided for both departureStartDate and departureEndDate, returns all routings with departures on that specific date.    
        - schema:
            type: string
            format: date
            example: '2021-04-01'
          in: query
          name: arrivalStartDate
          description: |
            Limit the result based on the earliest arrivalDate.
            - If provided without arrivalEndDate, returns all routings with arrivals from the specified arrivalStartDate.
            - If provided with arrivalEndDate, returns all routings with arrivals within the specified date range, inclusive of both dates.
            - If the same date is provided for both arrivalStartDate and arrivalEndDate, returns all routings with arrivals on that specific date.
        - schema:
            type: string
            format: date
            example: '2021-05-01'
          in: query
          name: arrivalEndDate
          description: |
            Limit the result based on the latest arrivalDate.
            - If provided without arrivalStartDate, returns all routings with arrivals up to the specified arrivalEndDate.
            - If provided with arrivalStartDate, returns all routings with arrivals within the specified date range, inclusive of both dates.
            - If the same date is provided for both arrivalStartDate and arrivalEndDate, returns all routings with arrivals on that specific date.
        - schema:
            type: integer
            example: 1
            format: int32
            minimum: 0
          in: query
          name: maxTranshipment
          description: |
            Specifies the maximum number of transhipments that the proposed routings can have in the response. By default, transhipments are allowed and the responses can have either direct routings or routings with transhipment. The default value of maximum transhipments is defined by the carrier for when the consumer does not provide a value. If the user sets the number of transhipments to 0, only direct routings can be returned in the response.

            **Note:** According to the DCSA definition, a “transhipment” specifically refers to transferring containers or cargo from one vessel to another, focusing exclusively on ocean transport. This means that, under the current interpretation, only vessel-to-vessel transfers are counted as transhipments. Moves between road, rail, or barge and a vessel (i.e., inland legs) do not fall under this definition and, therefore, should not be counted as transhipments.
        - schema:
            type: string
            enum:
              - CY
              - SD
              - CFS
            maxLength: 3
            example: CY
          in: query
          name: receiptTypeAtOrigin
          description: |
            Indicates the type of service offered at Origin. **Carriers can choose to define a default value when the consumer does not provide it.**
              - `CY` (Container yard (incl. rail ramp))  
              - `SD` (Store Door)  
              - `CFS` (Container Freight Station)
        - schema:
            type: string
            enum:
              - CY
              - SD
              - CFS
            maxLength: 3
            example: CY
          in: query
          name: deliveryTypeAtDestination
          description: |
            Indicates the type of service offered at Destination. **Carriers can choose to define a default value when the consumer does not provide it.**
              - `CY` (Container yard (incl. rail ramp))  
              - `SD` (Store Door)  
              - `CFS` (Container Freight Station)
        - schema:
            type: string
            default: DRY
            example: REEFER
          in: query
          name: cargoType
          description: |
            This parameter can influence:
            * the routing solutions returned
            * the feasibility of individual transport legs
            * the reported footprint values, when provided

            Possible values:
            - `DRY` (For DRY cargo)
            - `REEFER` (Reefer cargo)

            The default value is `DRY` in case this filter parameter is not used.
        - schema:
            type: integer
            format: int32
            default: 100
            example: 100
            minimum: 1
          in: query
          name: limit
          description: Specifies the maximum number of `Point-to-Point` objects to return.
        - schema:
            type: string
            maxLength: 1024
          in: query
          name: cursor
          description: A server generated value to specify a specific point in a collection result, used for pagination.
          example: fE9mZnNldHw9MTAmbGltaXQ9MTA
        - $ref: '#/components/parameters/Api-Version-Major'
      description: |
        Provides the product offering of single or multiple estimated end-to-end route options for a shipment in the pre-booking phase. This includes point-to-point specification of all transport legs, estimated timings, estimated schedules and interdependencies between transport legs.

        The list of solutions returned in the response can be tailored to a specific need by combining available query parameters.

        The minimum required query parameters are `placeOfReceipt` and `placeOfDelivery`. If no further query parameters are used to tailor the response, the provider of the GET endpoint will return their best suggestions in the response. 

        The `GET /v1/point-to-point-routes` endpoint can be implemented independently of having implemented the `GET /v1/port-schedules`  and `GET /v1/vessel-schedules`  endpoints.
  /v1/port-schedules:
    get:
      summary: Port Schedule
      tags:
        - Port Schedule
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PortSchedule'
          headers:
            API-Version:
              schema:
                type: string
                example: 1.0.2
              description: |
                SemVer used to indicate the version of the contract (API version) returned.
            Next-Page-Cursor:
              schema:
                type: string
                maxLength: 1024
                example: fE9mZnNldHw9MTAmbGltaXQ9MTA
              description: |
                The `Next-Page-Cursor` header contains a cursor value that points to the next page of results in a paginated API response.
                When an initial `GET` endpoint request includes the query parameter `limit=...` the API provider limits the number of items in the root array of the response to the specified limit. If the response would contain more items than the specified limit, the API provider includes only the first set of limit items and appends the following response header:
                `Next-Page-Cursor=fE9mZnNldHw9MTAmbGltaXQ9MTA`, a string that acts as a reference for the next page of results. The `Next-Page-Cursor` value is used in a subsequent request to retrieve the next page by passing it as a value in the `cursor`-query parameter: `cursor=fE9mZnNldHw9MTAmbGltaXQ9MTA`.

                To retrieve the next page, the API consumer sends a `GET` request to the endpoint URL with `cursor=fE9mZnNldHw9MTAmbGltaXQ9MTA` as query parameter along with the limit of items per page and any other query parameters used in the original request. Filter parameters may not be altered and MUST be preserved when requesting subsequent pages.
        '400':
          description: Bad Request
          headers:
            API-Version:
              schema:
                type: string
                example: 1.0.2
              description: |
                SemVer used to indicate the version of the contract (API version) returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Example 1:
                  value:
                    httpMethod: GET
                    requestUri: 'https://dcsa.org/cs/v1/port-schedule'
                    statusCode: 400
                    statusCodeText: Bad Request
                    providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962
                    errorDateTime: '2019-11-12T07:41:00+08:30'
                    errors:
                      - errorCode: 7005
                        property: port
                        value: SG
                        errorCodeText: invalidQuery
                        errorCodeMessage: Port does not exist
        '500':
          description: Internal Server Error
          headers:
            API-Version:
              schema:
                type: string
                example: 1.0.2
              description: |
                SemVer used to indicate the version of the contract (API version) returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Example 1:
                  value:
                    httpMethod: GET
                    requestUri: 'https://dcsa.org/cs/v1/port-schedule'
                    statusCode: 500
                    statusCodeText: Internal Server Error
                    statusCodeMessage: Cannot process request.
                    providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962
                    errorDateTime: '2019-11-12T07:41:00+08:30'
                    errors:
                      - errorCode: 7007
                        property: UNLocationCode
                        value: NA
                        errorCodeText: invalidQuery
                        errorCodeMessage: UNLocationCode does not exist
      operationId: get-v1-port-schedules
      description: |
        Provides, for a required specific port and starting date, the set of all vessels arriving and departing from the port with the corresponding estimated timestamps.

        The port must be identified by its UN Location Code. 

        The required query parameters are `UNLocationCode` and `date`. 

        If the requested port (identified with `UNLocationCode`) has multiple terminals (identified with `facilitySMDGCode`), the response will include a sorted list that provides all the arrivals and departures of the vessels for each terminal of the port (`UNLocationCode`). 

        The `GET /v1/port-schedules` endpoint can be implemented independently of having implemented the  `GET /v1/point-to-point-routes`  and `GET /v1/vessel-schedules`  endpoints. 
      parameters:
        - schema:
            type: string
            maxLength: 5
            example: NLAMS
            pattern: ^[A-Z]{2}[A-Z2-9]{3}$
            minLength: 5
          in: query
          name: UNLocationCode
          description: The UN Location code specifying where the place is located. Specifying this filter will only return the set of all vessels arriving and departing from the port and its terminals.
          required: true
        - schema:
            type: string
            format: date
            pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
            example: '2023-07-01'
          in: query
          name: date
          description: The date since when the estimated arrival and departures of vessels in a given port is required.
          required: true
        - $ref: '#/components/parameters/Api-Version-Major'
        - schema:
            type: integer
            format: int32
            default: 100
            example: 100
            minimum: 1
          in: query
          name: limit
          description: Specifies the maximum number of `Port Schedule` objects to return.
        - schema:
            type: string
            example: fE9mZnNldHw9MTAmbGltaXQ9MTA
            maxLength: 1024
          in: query
          name: cursor
          description: A server generated value to specify a specific point in a collection result, used for pagination.
  /v1/vessel-schedules:
    get:
      summary: Vessel Schedule
      tags:
        - Vessel Schedule
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ServiceSchedule'
          headers:
            API-Version:
              schema:
                type: string
                example: 1.0.2
              description: |
                SemVer used to indicate the version of the contract (API version) returned.
            Next-Page-Cursor:
              schema:
                type: string
                maxLength: 1024
                example: fE9mZnNldHw9MTAmbGltaXQ9MTA
              description: |
                The `Next-Page-Cursor` header contains a cursor value that points to the next page of results in a paginated API response.
                When an initial `GET` endpoint request includes the query parameter `limit=...` the API provider limits the number of items in the root array of the response to the specified limit. If the response would contain more items than the specified limit, the API provider includes only the first set of limit items and appends the following response header:
                `Next-Page-Cursor=fE9mZnNldHw9MTAmbGltaXQ9MTA`, a string that acts as a reference for the next page of results. The `Next-Page-Cursor` value is used in a subsequent request to retrieve the next page by passing it as a value in the `cursor`-query parameter: `cursor=fE9mZnNldHw9MTAmbGltaXQ9MTA`.

                To retrieve the next page, the API consumer sends a `GET` request to the endpoint URL with `cursor=fE9mZnNldHw9MTAmbGltaXQ9MTA` as query parameter along with the limit of items per page and any other query parameters used in the original request. Filter parameters may not be altered and MUST be preserved when requesting subsequent pages.
        '400':
          description: Bad Request
          headers:
            API-Version:
              schema:
                type: string
                example: 1.0.2
              description: |
                SemVer used to indicate the version of the contract (API version) returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Example 1:
                  value:
                    httpMethod: GET
                    requestUri: 'https://dcsa.org/cs/v1/vessel-schedule'
                    statusCode: 400
                    statusCodeText: Bad Request
                    providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962
                    errorDateTime: '2019-11-12T07:41:00+08:30'
                    errors:
                      - errorCode: 7007
                        property: UNLocationCode
                        value: NA
                        errorCodeText: invalidQuery
                        errorCodeMessage: UNLocationCode does not exist
        '500':
          description: Internal Server Error
          headers:
            API-Version:
              schema:
                type: string
                example: 1.0.2
              description: |
                SemVer used to indicate the version of the contract (API version) returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Example 1:
                  value:
                    httpMethod: GET
                    requestUri: 'https://dcsa.org/cs/v1/vessel-schedule'
                    statusCode: 500
                    statusCodeText: Internal Server Error
                    statusCodeMessage: Cannot process request.
                    providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962
                    errorDateTime: '2019-11-12T07:41:00+08:30'
                    errors:
                      - errorCode: 7007
                        property: UNLocationCode
                        value: NA
                        errorCodeText: invalidQuery
                        errorCodeMessage: UNLocationCode does not exist
      operationId: get-v1-vessel-schedule
      parameters:
        - schema:
            type: string
            minLength: 7
            maxLength: 8
            pattern: ^\d{7,8}$
            example: '9321483'
          in: query
          name: vesselIMONumber
          description: The unique reference for a registered Vessel. The reference is the International Maritime Organisation (IMO) number, also sometimes known as the Lloyd's register code, which does not change during the lifetime of the vessel.
        - schema:
            type: string
            maxLength: 50
            pattern: ^\S(?:.*\S)?$
            example: King of the Seas
          in: query
          name: vesselName
          description: The name of a vessel. The result will only return schedules including the vessel with the specified name.  Be aware that the vesselName is not unique and might match multiple vessels.
        - schema:
            type: string
            maxLength: 11
            example: FE1
          in: query
          name: carrierServiceCode
          description: The carrier specific service code to filter by. The result will only return schedules including the service code.
        - schema:
            type: string
            pattern: ^SR\d{5}[A-Z]$
            maxLength: 8
            minLength: 8
            example: SR12345A
          in: query
          name: universalServiceReference
          description: The Universal Service Reference (USR) as defined by DCSA to filter by.
        - schema:
            type: string
            maxLength: 50
            example: 2103S
          in: query
          name: carrierVoyageNumber
          description: The carrier specific identifier of a Voyage - can be both `importVoyageNumber` and `exportVoyageNumber`. The result will only return schedules including the Ports where `carrierVoyageNumber` is either `carrierImportVoyageNumber` or `carrierExportVoyageNumber`.
        - schema:
            type: string
            pattern: ^\d{2}[0-9A-Z]{2}[NEWSR]$
            maxLength: 5
            example: 2201N
          in: query
          name: universalVoyageReference
          description: The Universal Reference of a Voyage - can be both `importUniversalVoyageReference` and `exportUniversalVoyageReference`. The result will only return schedules including the Ports where `universalVoyageReference` is either `importUniversalVoyageReference` or `exportUniversalVoyageReference`.
        - schema:
            type: string
            pattern: ^[A-Z]{2}[A-Z2-9]{3}$
            minLength: 5
            maxLength: 5
            example: NLAMS
          in: query
          name: UNLocationCode
          description: The UN Location Code specifying where a port is located.  Specifying this filter will only return schedules including entire Voyages related to this particular UN Location Code.
        - schema:
            type: string
            maxLength: 6
            example: APM
          in: query
          name: facilitySMDGCode
          description: The facilitySMDGCode specifying a specific facility (using SMDG Code). Be aware that the `facilitySMDGCode` does not contain a `UNLocationCode` - this must be specified in the `UNLocationCode` filter.  Specifying this filter will only return schedules including entire Voyages related to this particular `facilitySMDGCode`. It is recommended to specify a value for this query parameter only if a value is provided for `UNLocationCode`.
        - schema:
            type: string
            example: MAEU
            maxLength: 10
          in: query
          name: vesselOperatorCarrierCode
          description: The carrier who is in charge of the vessel operation based on either the SMDG or SCAC code lists.
        - schema:
            type: string
            format: date
            example: '2020-04-06'
          in: query
          name: startDate
          description: |
            The start date of the period for which schedule information is requested. If a date of any Timestamp (ATA, ETA or PTA) inside a PortCall matches a date on or after (≥) the `startDate` the entire Voyage (import- and export-Voyage) matching the PortCall will be included in the result. All matching is done towards local Date at the place of the port call.
            If this filter is not provided, the default value is **3 months** prior to the request time.
        - schema:
            type: string
            format: date
            example: '2020-04-10'
          in: query
          name: endDate
          description: |
            The end date of the period for which schedule information is requested. If a date of any Timestamp (ATA, ETA or PTA) inside a PortCall matches a date on or before (≤) the `endDate` the entire Voyage(import- and export-Voyage) matching the PortCall will be included in the result. All matching is done towards local Date at the place of the port call.  
            If this filter is not provided, the default value is **6 months** after the request time.
        - schema:
            type: integer
            format: int32
            default: 100
            example: 100
            minimum: 1
          in: query
          name: limit
          description: Specifies the maximum number of `Service Schedule` objects to return.
        - schema:
            type: string
            example: fE9mZnNldHw9MTAmbGltaXQ9MTA
            maxLength: 1024
          in: query
          name: cursor
          description: A server generated value to specify a specific point in a collection result, used for pagination.
        - $ref: '#/components/parameters/Api-Version-Major'
      description: |
        Provides, for a required specific service and/or voyage and/or vessel and/or location, the timetable of estimated departure and arrival times for each port call on the rotation of the vessel(s).

        The list of schedules returned in the response can be tailored to specific needs by combining available query parameters. 

        A filter parameter or a combination of filter parameters MUST always be provided to call the endpoint. Examples of typical query parameters and expected payload returned in the response:

        - a) `carrierServiceCode`: Get all vessels and their full voyages within a service   

        - b) `carrierServiceCode` **&** `carrierVoyageNumber`: Get a specific full voyage within a service

        - c) `carrierServiceCode` **&** `vesselIMONumber`: Get a specific vessel's full voyages within a service. 

        - d) `vesselIMONumber`: Get all full voyages for a specific vessel across all the services in which it is involved.

        - e) `UNLocationCode`: Get all vessels and their full voyages where the specific `UNLocationCode` is involved

        - f) `UNLocationCode` **&** `facilitySMDGCode`: Get all vessels and their full voyages where the specific  `UNLocationCode` and `facilitySMDGCode` is involved

        Other combinations using `vesselName`, `universalServiceReference`, `universalVoyageReference`, `vesselOperatorCarrierCode`, `startDate`, `endDate` are possible. 

        The filter parameters `startDate` and `endDate` MUST always be used in combination with any of the other available parameters.

        The resulting payload returned in the responses will always include **entire voyage(s) being matched**. This means that even though a filter only matches a single `Port` (`UNLocationCode`) in a `Voyage` or a single `Timestamp` within a `Port` in a `Voyage` - **the entire Voyage matched** is returned. If the `carrierImportVoyageNumber` of the `Port` differs from the `carrierExportVoyageNumber` of the `Port` then the **entire Voyage** for both these Voyage numbers are included. An example of this is when `&UNLocationCode=DEHAM` is used as a filter parameter. In this case **entire Voyages** would be listed where `DEHAM` is a `Port`.

        Be aware that it is possible to specify filters that are mutually exclusive resulting in an empty response list. An example of this could be when both using `vesselIMONumber` and `vesselName` filters at the same time: `&vesselIMONumber=9321483&vesselName=King of the Seas`. If no `Vessel` exists where `vesselIMONumber` is **9321483** and `vesselName` is **King of the Seas** then the result will be an empty list. 

        If no `startDate` filter is provided, then **3 months** before the request date should be used as default. If no `endDate` filter is provided, then **6 months** after the request date should be used as default. The endpoint provider can customize these based on their business definitions and inform the consumers what to expect in a response when these filters are not used. 

        The `GET /v1/vessel-schedules` endpoint can be implemented independently of having implemented the  `GET /v1/point-to-point-routes`  and `GET /v1/port-schedules`  endpoints. 

        **IMPORTANT**: This endpoint is for carriers to make available vessel schedules to BCO, LSP, and Solution Platforms, with a commercial purpose; this is out of the boundaries of their vessel schedules alignment with other carriers and terminals for operational purposes for which the Operational Vessel Schedules [API](https://app.swaggerhub.com/apis/dcsaorg/DCSA_OVS/3.0.0) is used between carriers, and carriers and terminals. 
components:
  schemas:
    PlaceOfReceipt:
      title: Place of Receipt
      type: object
      description: |
        The Location specifying where the place of receipt is located.
      required:
        - facilityTypeCode
        - location
        - dateTime
      properties:
        facilityTypeCode:
          description: |
            The code to identify the specific type of facility. The code indicates which role the facility plays during the transportCall.
            - `BORD` (Border)
            - `CLOC` (Customer Location)
            - `COFS` (Container Freight Station)
            - `OFFD` (Off Dock Storage)
            - `DEPO` (Depot)
            - `INTE` (Inland Terminal)
            - `POTE` (Port Terminal)
            - `PBPL` (Pilot Boarding Place)
            - `BRTH` (Berth)
            - `RAMP` (Ramp)
            - `WAYP` (Waypoint)
          example: POTE
          maxLength: 4
          type: string
        location:
          $ref: '#/components/schemas/Location'
        dateTime:
          type: string
          format: date-time
          example: '2025-01-14T09:21:00+01:00'
          description: The local date and time, when the event will take place.
    PlaceOfDelivery:
      title: Place of Delivery
      type: object
      description: |
        The Location specifying where the place of delivery is located.
      required:
        - facilityTypeCode
        - location
        - dateTime
      properties:
        facilityTypeCode:
          description: |
            The code to identify the specific type of facility. The code indicates which role the facility plays during the transportCall.
            - `BORD` (Border)
            - `CLOC` (Customer Location)
            - `COFS` (Container Freight Station)
            - `OFFD` (Off Dock Storage)
            - `DEPO` (Depot)
            - `INTE` (Inland Terminal)
            - `POTE` (Port Terminal)
            - `PBPL` (Pilot Boarding Place)
            - `BRTH` (Berth)
            - `RAMP` (Ramp)
            - `WAYP` (Waypoint)
          example: POTE
          maxLength: 4
          type: string
        location:
          $ref: '#/components/schemas/Location'
        dateTime:
          type: string
          format: date-time
          example: '2025-01-14T09:21:00+01:00'
          description: The local date and time, when the event will take place.
    PlaceOfArrival:
      title: Place of Arrival
      type: object
      description: |
        The Location specifying where the place of arrival is located.
      required:
        - facilityTypeCode
        - location
        - dateTime
      properties:
        transportCallReference:
          type: string
          example: SR11111X-9321483-2107W-NLAMS-ACT-1-1
          maxLength: 100
          description: |
            The unique reference for the arrival transport call. It's the vessel operator's responsibility to provide the Transport Call Reference, other parties are obliged to pick it up and use it. It can take the form of Port Call References as defined in OVS Definitions Document, or alternatively a reference as defined by the vessel operator.

            **Note:** This property takes precedence over the `transportCallReference` in the Vessel-Transport or Barge-Transport objects. If both this property and a `transportCallReference` in the Vessel-Transport or Barge-Transport objects are provided- the `transportCallReference` in those objects must be ignored.
        facilityTypeCode:
          description: |
            The code to identify the specific type of facility. The code indicates which role the facility plays during the transportCall.
            - `BORD` (Border)
            - `CLOC` (Customer Location)
            - `COFS` (Container Freight Station)
            - `OFFD` (Off Dock Storage)
            - `DEPO` (Depot)
            - `INTE` (Inland Terminal)
            - `POTE` (Port Terminal)
            - `PBPL` (Pilot Boarding Place)
            - `BRTH` (Berth)
            - `RAMP` (Ramp)
            - `WAYP` (Waypoint)
          example: POTE
          maxLength: 4
          type: string
        location:
          $ref: '#/components/schemas/Location'
        dateTime:
          type: string
          format: date-time
          example: '2025-01-14T09:21:00+01:00'
          description: The local date and time, when the event will take place.
    PlaceOfDeparture:
      title: Place of Departure
      type: object
      description: |
        The Location specifying where the place of departure is located.
      required:
        - facilityTypeCode
        - location
        - dateTime
      properties:
        transportCallReference:
          type: string
          example: SR11111X-9321483-2107W-NLAMS-ACT-1-1
          maxLength: 100
          description: |
            The unique reference for the departure transport call. It's the vessel operator's responsibility to provide the Transport Call Reference, other parties are obliged to pick it up and use it. It can take the form of Port Call References as defined in OVS Definitions Document, or alternatively a reference as defined by the vessel operator.

            **Note:** This property takes precedence over the `transportCallReference` in the Vessel-Transport or Barge-Transport objects. If both this property and a `transportCallReference` in the Vessel-Transport or Barge-Transport objects are provided- the `transportCallReference` in those objects must be ignored.
        facilityTypeCode:
          description: |
            The code to identify the specific type of facility. The code indicates which role the facility plays during the transportCall.
            - `BORD` (Border)
            - `CLOC` (Customer Location)
            - `COFS` (Container Freight Station)
            - `OFFD` (Off Dock Storage)
            - `DEPO` (Depot)
            - `INTE` (Inland Terminal)
            - `POTE` (Port Terminal)
            - `PBPL` (Pilot Boarding Place)
            - `BRTH` (Berth)
            - `RAMP` (Ramp)
            - `WAYP` (Waypoint)
          example: POTE
          maxLength: 4
          type: string
        location:
          $ref: '#/components/schemas/Location'
        dateTime:
          type: string
          format: date-time
          example: '2025-01-14T09:21:00+01:00'
          description: The local date and time, when the event will take place.
    PointToPoint:
      title: Point to Point
      type: object
      required:
        - placeOfReceipt
        - placeOfDelivery
        - legs
      properties:
        placeOfReceipt:
          $ref: '#/components/schemas/PlaceOfReceipt'
        placeOfDelivery:
          $ref: '#/components/schemas/PlaceOfDelivery'
        receiptTypeAtOrigin:
          type: string
          maxLength: 3
          description: |
            Indicates the type of service offered at `Origin`. The options are:
            - `CY` (Container yard (incl. rail ramp))
            - `SD` (Store Door)
            - `CFS` (Container Freight Station)
          enum:
            - CY
            - SD
            - CFS
          example: CY
        deliveryTypeAtDestination:
          type: string
          maxLength: 3
          description: |
            Indicates the type of service offered at `Destination`. The options are:
            - `CY` (Container yard (incl. rail ramp))
            - `SD` (Store Door)
            - `CFS` (Container Freight Station)
          enum:
            - CY
            - SD
            - CFS
          example: CY
        cutOffTimes:
          type: array
          description: A list of cut-offs times provided by the carrier when available. A cut-off time indicates the latest date and time by which a task must be completed. For example, the latest date and time by which a container must be delivered to a terminal to be loaded on a vessel, or where certain documentation must be provided by the Shipper.
          items:
            $ref: '#/components/schemas/CutOffTime'
        solutionNumber:
          type: integer
          format: int32
          minimum: 1
          example: 1
          description: Solution number, starting with 1. Used to group and identify similar or same routings in the response as per the carrier commercial definitions.
        routingReference:
          type: string
          pattern: ^\S(?:.*\S)?$
          maxLength: 5000
          description: |
            A reference to be used when creating a **Booking** in the **Booking API**.
          example: Route123
        transitTime:
          type: integer
          description: The estimated total time in days that it takes a shipment to move from place of receipt to place of delivery. Transit time includes stop-over time during transhipments and waiting time at connection points, if applicable, thus can vary between the same locations.
          format: int32
          example: 10
        solutionFootprint:
          type: object
          description: |
            Estimated footprint emission calculation for the full routing solution.
          properties:
            co2:
              type: number
              format: double
              description: |
                CO<sub>2</sub> (Carbon Dioxide) emissions in metric tonnes (t).
              example: 506.4
            co2e:
              type: number
              format: double
              description: |
                CO<sub>2</sub>e (Carbon Dioxide equivalent) emissions in metric tonnes (t).
              example: 520.7
            sox:
              type: number
              format: double
              description: |
                SO<sub>x</sub> (Sulphur Oxide) emissions in kilograms (kg).
              example: 12.4
            nox:
              type: number
              format: double
              description: |
                NO<sub>x</sub> (Nitrogen Oxide) emissions in kilograms (kg).
              example: 15.4
            pm10:
              type: number
              format: double
              description: |
                PM<sub>10</sub> (Small Particle) emissions in kilograms (kg).
              example: 0.8
        legs:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/Leg'
    PortSchedule:
      title: Port Schedule
      type: object
      required:
        - location
      properties:
        location:
          $ref: '#/components/schemas/PortScheduleLocation'
        vesselSchedules:
          type: array
          items:
            $ref: '#/components/schemas/Schedule'
    Schedule:
      title: Schedule
      type: object
      required:
        - servicePartners
        - isDummyVessel
        - timestamps
      properties:
        universalServiceReference:
          type: string
          example: SR12345A
          pattern: ^SR\d{5}[A-Z]$
          maxLength: 8
          minLength: 8
          description: |
            A global unique service reference, as per DCSA standard, agreed by VSA partners for the service. The service reference must match the regular expression pattern: `SR\d{5}[A-Z]`. The letters `SR` followed by `5` digits, followed by a checksum-character as a capital letter from `A to Z`.
        servicePartners:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/ServicePartnerSchedule'
        vessel:
          $ref: '#/components/schemas/Vessel'
        isDummyVessel:
          type: boolean
          description: This property can be set to `true` when no vessel has been assigned, indicating that the `vesselIMONumber` does not exist.
        universalImportVoyageReference:
          type: string
          description: |
            A global unique voyage reference for the import Voyage, as per DCSA standard, agreed by VSA partners for the voyage.The voyage reference must match the regular expression pattern: `\d{2}[0-9A-Z]{2}[NEWSR]`
 
            - `2 digits` for the year
            - `2 alphanumeric characters` for the sequence number of the voyage
            - `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip).

          pattern: ^\d{2}[0-9A-Z]{2}[NEWSR]$
          example: 2103N
          minLength: 5
          maxLength: 5
        universalExportVoyageReference:
          type: string
          description: |
            A global unique voyage reference for the export Voyage, as per DCSA standard, agreed by VSA partners for the voyage.The voyage reference must match the regular expression pattern: `\d{2}[0-9A-Z]{2}[NEWSR]`
 
            - `2 digits` for the year
            - `2 alphanumeric characters` for the sequence number of the voyage
            - `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip).

          pattern: ^\d{2}[0-9A-Z]{2}[NEWSR]$
          example: 2103N
          minLength: 5
          maxLength: 5
        timestamps:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/Timestamp'
        cutOffTimes:
          type: array
          description: A list of cut-offs times provided by the carrier when available. A cut-off time indicates the latest date and time by which a task must be completed. For example, the latest date and time by which a container must be delivered to a terminal to be loaded on a vessel, or where certain documentation must be provided by the Shipper.
          items:
            $ref: '#/components/schemas/CutOffTime'
    TransportCall:
      title: Transport Call
      type: object
      description: |
        A transportCall in the schedule. A transportCall can be either just a Port or further specified as a terminalCall.
      required:
        - transportCallReference
        - carrierImportVoyageNumber
        - timestamps
      properties:
        portVisitReference:
          type: string
          description: The unique reference that can be used to link different `transportCallReferences` to the same port visit. The reference is provided by the port to uniquely identify a port call.
          maxLength: 50
          example: NLRTM1234589
        transportCallReference:
          type: string
          maxLength: 100
          description: The unique reference for a transport call. It's the vessel operator's responsibility to provide the Transport Call Reference, other parties are obliged to pick it up and use it. It can take the form of Port Call References as defined in OVS Definitions Document, or alternatively a reference as defined by the vessel operator.
          example: SR11111X-9321483-2107W-NLRTM-HPD2-1-1
        carrierImportVoyageNumber:
          type: string
          maxLength: 50
          pattern: ^\S(?:.*\S)?$
          example: 2103N
          description: The identifier of an import voyage. The carrier-specific identifier of the import Voyage.
        carrierExportVoyageNumber:
          type: string
          maxLength: 50
          pattern: ^\S(?:.*\S)?$
          example: 2103S
          description: The identifier of an export voyage. The carrier-specific identifier of the export Voyage.
        universalImportVoyageReference:
          type: string
          pattern: ^\d{2}[0-9A-Z]{2}[NEWSR]$
          example: 2103N
          description: |
            A global unique voyage reference for the import Voyage, as per DCSA standard, agreed by VSA partners for the voyage.The voyage reference must match the regular expression pattern: `\d{2}[0-9A-Z]{2}[NEWSR]`
 
            - `2 digits` for the year
            - `2 alphanumeric characters` for the sequence number of the voyage
            - `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip).

          maxLength: 5
          minLength: 5
        universalExportVoyageReference:
          type: string
          pattern: ^\d{2}[0-9A-Z]{2}[NEWSR]$
          example: 2103N
          maxLength: 5
          minLength: 5
          description: |
            A global unique voyage reference for the export Voyage, as per DCSA standard, agreed by VSA partners for the voyage.The voyage reference must match the regular expression pattern: `\d{2}[0-9A-Z]{2}[NEWSR]`
 
            - `2 digits` for the year
            - `2 alphanumeric characters` for the sequence number of the voyage
            - `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip).

        cutOffTimes:
          type: array
          description: A list of cut-offs times provided by the carrier when available. A cut-off time indicates the latest date and time by which a task must be completed. For example, the latest date and time by which a container must be delivered to a terminal to be loaded on a vessel, or where certain documentation must be provided by the Shipper.
          items:
            $ref: '#/components/schemas/CutOffTime'
        location:
          $ref: '#/components/schemas/TransportCallLocation'
        timestamps:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/Timestamp'
    Timestamp:
      title: Timestamp
      type: object
      description: |
        Timestamp defined by a type (Arrival or Departure), a classifier (Planned, Estimated or Actual) and a date and time.
      required:
        - eventTypeCode
        - eventClassifierCode
        - eventDateTime
      properties:
        eventTypeCode:
          type: string
          enum:
            - ARRI
            - DEPA
          example: ARRI
          description: |
            Identifier for type of transportEvent.

            - `ARRI` (Arrived)
            - `DEPA` (Departed)
        eventClassifierCode:
          type: string
          enum:
            - PLN
            - EST
            - ACT
          example: PLN
          description: |
            Code for the event classifier. Values can vary depending on eventType.

            Possible values are:
            - `ACT` (Actual)
            - `EST` (Estimated)
            - `PLN` (Planned)
        eventDateTime:
          type: string
          format: date-time
          description: The local date and time, when the event takes place.
          example: '2025-01-14T09:21:00+01:00'
    ServiceSchedule:
      title: Service Schedule
      type: object
      required:
        - carrierServiceName
        - carrierServiceCode
        - vesselSchedules
      properties:
        carrierServiceName:
          type: string
          description: The name of the service.
          maxLength: 50
          pattern: ^\S(?:.*\S)?$
          example: Great Lion Service
        carrierServiceCode:
          type: string
          maxLength: 11
          example: FE1
          pattern: ^\S(?:.*\S)?$
          description: The carrier-specific code of the service for which the schedule details are published.
        universalServiceReference:
          type: string
          pattern: ^SR\d{5}[A-Z]$
          maxLength: 8
          minLength: 8
          example: SR12345A
          description: A global unique service reference, as per DCSA standard, agreed by VSA partners for the service.
        vesselSchedules:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/VesselSchedule'
    VesselSchedule:
      title: Vessel Schedule
      type: object
      description: |
        The timetable of departure and arrival times for each `TransportCall` on a Service of the vessel in question.
      required:
        - isDummyVessel
      properties:
        vessel:
          $ref: '#/components/schemas/Vessel'
        isDummyVessel:
          type: boolean
          description: This property can be set to `true` when no vessel has been assigned, indicating that the `vesselIMONumber` does not exist.
        transportCalls:
          type: array
          items:
            $ref: '#/components/schemas/TransportCall'
    CutOffTime:
      title: Cut-Off Time
      type: object
      description: Cut Off Times.
      required:
        - cutOffDateTimeCode
        - cutOffDateTime
      properties:
        cutOffDateTimeCode:
          type: string
          description: |
            Code for the cut-off time. Possible values are:
              - `DCO` (Documentation cut-off)
              - `VCO` (VGM cut-off)
              - `FCO` (FCL delivery cut-off)
              - `LCO` (LCL delivery cut-off) **Condition:** only when the `Receipt Type at Origin` is `CFS`
              - `PCO` (Port cut-off)
              - `ECP` (Empty container pick-up date and time)
              - `EFC` (Earliest full-container delivery date)
              - `RCO` (Reefer cut-off)
              - `DGC` (Dangerous Goods cut-off)
              - `OBC` (OOG/BB cut-off)
              - `TCO` (Transhipment cut-off)
              - `STA` (Standard booking acceptance)
              - `SPA` (Special booking acceptance)
              - `CUA` (Customs Acceptance)
              - `AFC` (Advanced filling cut-off)
          maxLength: 3
          example: DCO
        cutOffDateTime:
          type: string
          format: date-time
          description: Estimated cut-off time expressed in local time with offset.
          example: '2019-11-12T07:41:00-08:30'
    Address:
      title: Address
      type: object
      description: An object for storing address related information.
      required:
        - street
        - city
        - countryCode
      properties:
        street:
          type: string
          example: Ruijggoordweg
          description : The name of the street.
          maxLength: 70
        streetNumber:
          type: string
          example: '100'
          description: The number of the street.
          maxLength: 50
        floor:
          type: string
          example: N/A
          pattern: ^\S(?:.*\S)?$
          description: The floor of the street number.
          maxLength: 50
        postCode:
          type: string
          example: 1047 HM
          description: The post code.
          maxLength: 10
        city:
          type: string
          example: Amsterdam
          pattern: ^\S(?:.*\S)?$
          description: The name of the city.
          maxLength: 35
        stateRegion:
          type: string
          example: North Holland
          description: The name of the state/region.
          maxLength: 65
        countryCode:
          type: string
          pattern: ^[A-Z]{2}$
          minLength: 2
          maxLength: 2
          description: |
            The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)
          example: NL
    ErrorResponse:
      title: Error Response
      type: object
      description: Unexpected error
      required:
        - httpMethod
        - requestUri
        - statusCode
        - statusCodeText
        - errorDateTime
        - errors
      properties:
        httpMethod:
          type: string
          example: POST
          enum:
            - GET
            - HEAD
            - POST
            - PUT
            - DELETE
            - OPTION
            - PATCH
          description: The HTTP method used to make the request e.g. `GET`, `POST`, etc
        requestUri:
          type: string
          description: The URI that was requested.
          example: /v1/events
        statusCode:
          type: integer
          description: The HTTP status code returned.
          format: int32
          example: 400
        statusCodeText:
          type: string
          description: A standard short description corresponding to the HTTP status code.
          example: Bad Request
          maxLength: 50
        statusCodeMessage:
          type: string
          description: A long description corresponding to the HTTP status code with additional information.
          maxLength: 200
          example: The supplied data could not be accepted
        providerCorrelationReference:
          type: string
          description: A unique identifier to the HTTP request within the scope of the API provider.
          maxLength: 100
          example: 4426d965-0dd8-4005-8c63-dc68b01c4962
        errorDateTime:
          type: string
          description: The DateTime corresponding to the error occurring.
          example: '2019-11-12T07:41:00Z'
          format: date-time
        errors:
          type: array
          description: An array of errors providing more detail about the root cause.
          minItems: 1
          items:
            $ref: '#/components/schemas/DetailedError'
    Vessel:
      title: Vessel
      type: object
      description: |
        Static vessel information like `IMONumber`, `MMSINumber`, `name`, `flag`, `callSign` and operator.
      properties:
        vesselIMONumber:
          type: string
          description: The unique reference for a registered Vessel. The reference is the International Maritime Organisation (IMO) number, also sometimes known as the Lloyd's register code, which does not change during the lifetime of the vessel.
          example: '9321483'
          pattern: ^\d{7,8}$
          minLength: 7
          maxLength: 8
        MMSINumber:
          type: string
          description: Maritime Mobile Service Identities (MMSIs) are nine-digit numbers used by maritime digital selective calling (DSC), automatic identification systems (AIS) and certain other equipment to uniquely identify a ship or a coast radio station.
          pattern: ^\d{9}$
          minLength: 9
          maxLength: 9
          example: '278111222'
        name:
          type: string
          description: The name of the Vessel given by the Vessel Operator and registered with IMO.
          example: King of the Seas
          maxLength: 50
          pattern: ^\S(?:.*\S)?$
        flag:
          type: string
          description: The flag of the nation whose laws the vessel is registered under. This is the [ISO 3166](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) two-letter country code.
          pattern: ^[A-Z]{2}$
          maxLength: 2
          minLength: 2
          example: DE
        callSign:
          type: string
          description: A unique alphanumeric identity that belongs to the vessel and is assigned by the International Telecommunication Union (ITU). It consists of a three letter alphanumeric prefix that indicates nationality, followed by one to four characters to identify the individual vessel. For instance, vessels registered under Denmark are assigned the prefix ranges 5PA-5QZ, OUAOZZ, and XPA-XPZ. The Call Sign changes whenever a vessel changes its flag.
          pattern: ^\S(?:.*\S)?$
          example: NCVV
          maxLength: 10
        operatorCarrierCode:
          type: string
          description: The carrier who is in charge of the vessel operation based on either the SMDG or SCAC code lists.
          example: MAEU
          maxLength: 10
        operatorCarrierCodeListProvider:
          type: string
          description: |
            Identifies the code list provider used for the operator and partner carriercodes.
            - `SMDG` (Ship Message Design Group)
            - `NMFTA` (National Motor Freight Traffic Association)
          example: NMFTA
          enum:
            - SMDG
            - NMFTA
    Barge:
      title: Barge
      type: object
      description: |
        Static barge information like `IMONumber`, `MMSINumber`, `name`, `flag`, `callSign` and operator.
      properties:
        vesselIMONumber:
          type: string
          description: The unique reference for a registered Vessel. The reference is the International Maritime Organisation (IMO) number, also sometimes known as the Lloyd's register code, which does not change during the lifetime of the vessel.
          example: '9321483'
          pattern: ^\d{7,8}$
          minLength: 7
          maxLength: 8
        MMSINumber:
          type: string
          description: Maritime Mobile Service Identities (MMSIs) are nine-digit numbers used by maritime digital selective calling (DSC), automatic identification systems (AIS) and certain other equipment to uniquely identify a ship or a coast radio station.
          pattern: ^\d{9}$
          minLength: 9
          maxLength: 9
          example: '278111222'
        name:
          type: string
          description: The name of the Vessel given by the Vessel Operator and registered with IMO.
          example: King of the Seas
          maxLength: 50
          pattern: ^\S(?:.*\S)?$
        flag:
          type: string
          description: The flag of the nation whose laws the vessel is registered under. This is the ISO 3166 two-letter country code.
          pattern: ^[A-Z]{2}$
          maxLength: 2
          minLength: 2
          example: DE
        callSign:
          type: string
          description: A unique alphanumeric identity that belongs to the vessel and is assigned by the International Telecommunication Union (ITU). It consists of a three letter alphanumeric prefix that indicates nationality, followed by one to four characters to identify the individual vessel. For instance, vessels registered under Denmark are assigned the prefix ranges 5PA-5QZ, OUAOZZ, and XPA-XPZ. The Call Sign changes whenever a vessel changes its flag.
          pattern: ^\S(?:.*\S)?$
          example: NCVV
          maxLength: 10
        operatorCarrierCode:
          type: string
          description: The carrier who is in charge of the vessel operation based on either the SMDG or SCAC code lists.
          example: MAEU
          maxLength: 10
        operatorCarrierCodeListProvider:
          type: string
          description: |
            Identifies the code list provider used for the operator and partner carriercodes.
            - `SMDG` (Ship Message Design Group)
            - `NMFTA` (National Motor Freight Traffic Association)
          example: NMFTA
          enum:
            - SMDG
            - NMFTA
    VesselTransport:
      title: Vessel Transport
      type: object
      description: Transport mode Vessel.
      required:
        - modeOfTransport
      properties:
        modeOfTransport:
          type: string
          description: The mode of transport as defined by DCSA. For the Vessel Transport mode this needs to be `VESSEL`.
          enum:
            - VESSEL
          example: VESSEL
        portVisitReference:
          type: string
          example: NLAMS1234589
          maxLength: 50
          description: The unique reference that can be used to link different `transportCallReferences` to the same port visit. The reference is provided by the port to uniquely identify a port call.
        transportCallReference:
          type: string
          deprecated: true
          example: SR11111X-9321483-2107W-NLAMS-ACT-1-1
          maxLength: 100
          description: |
            The unique reference for a transport call. It's the vessel operator's responsibility to provide the Transport Call Reference, other parties are obliged to pick it up and use it. It can take the form of Port Call References as defined in OVS Definitions Document, or alternatively a reference as defined by the vessel operator.

            **Deprecated:** Please use the `transportCallReference` (in **Departure** object) or `transportCallReference` (in **Arrival** object) in order to specify what the **TransportCall** is linked to. If provided in either `Arrival` or `Departure` object - this property must be ignored.
        servicePartners:
          type: array
          items:
            $ref: '#/components/schemas/ServicePartner'
        universalServiceReference:
          type: string
          description: |
            A global unique service reference, as per DCSA standard, agreed by VSA partners for the service. The service reference must match the regular expression pattern: `SR\d{5}[A-Z]`. The letters `SR` followed by `5` digits, followed by a checksum-character as a capital letter from `A to Z`.
          example: SR12345A
          pattern: ^SR\d{5}[A-Z]$
          maxLength: 8
          minLength: 8
        universalExportVoyageReference:
          type: string
          description: |
            A global unique voyage reference for the export Voyage, as per DCSA standard, agreed by VSA partners for the voyage. The voyage reference must match the regular expression pattern: `\d{2}[0-9A-Z]{2}[NEWSR]`
 
            - `2 digits` for the year
            - `2 alphanumeric characters` for the sequence number of the voyage
            - `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip).

          pattern: ^\d{2}[0-9A-Z]{2}[NEWSR]$
          minLength: 5
          maxLength: 5
          example: 2103N
        universalImportVoyageReference:
          type: string
          description: |
            A global unique voyage reference for the import Voyage, as per DCSA standard, agreed by VSA partners for the voyage. The voyage reference must match the regular expression pattern: `\d{2}[0-9A-Z]{2}[NEWSR]`
 
            - `2 digits` for the year
            - `2 alphanumeric characters` for the sequence number of the voyage
            - `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip).

          pattern: ^\d{2}[0-9A-Z]{2}[NEWSR]$
          minLength: 5
          maxLength: 5
          example: 2103N
        vessel:
          $ref: '#/components/schemas/Vessel'
    BargeTransport:
      title: Barge Transport
      type: object
      description: Transport mode Barge.
      required:
        - modeOfTransport
      properties:
        modeOfTransport:
          type: string
          description: The mode of transport as defined by DCSA. For the Barge Transport mode this needs to be `BARGE`.
          enum:
            - BARGE
          example: BARGE
        portVisitReference:
          type: string
          example: NLAMS1234589
          maxLength: 50
          description: The unique reference that can be used to link different `transportCallReferences` to the same port visit. The reference is provided by the port to uniquely identify a port call.
        transportCallReference:
          type: string
          deprecated: true
          example: SR11111X-9321483-2107W-NLAMS-ACT-1-1
          maxLength: 100
          description: |
            The unique reference for a transport call. It's the vessel operator's responsibility to provide the Transport Call Reference, other parties are obliged to pick it up and use it. It can take the form of Port Call References as defined in OVS Definitions Document, or alternatively a reference as defined by the vessel operator.

            **Deprecated:** Please use the `transportCallReference` (in **Departure** object) or `transportCallReference` (in **Arrival** object) in order to specify what the **TransportCall** is linked to. If provided in either `Arrival` or `Departure` object - this property must be ignored.
        servicePartners:
          type: array
          items:
            $ref: '#/components/schemas/ServicePartner'
        universalServiceReference:
          type: string
          description: |
            A global unique service reference, as per DCSA standard, agreed by VSA partners for the service. The service reference must match the regular expression pattern: `SR\d{5}[A-Z]`. The letters `SR` followed by `5` digits, followed by a checksum-character as a capital letter from `A to Z`.
          example: SR12345A
          pattern: ^SR\d{5}[A-Z]$
          maxLength: 8
          minLength: 8
        universalExportVoyageReference:
          type: string
          description: |
            A global unique voyage reference for the export Voyage, as per DCSA standard, agreed by VSA partners for the voyage.The voyage reference must match the regular expression pattern: `\d{2}[0-9A-Z]{2}[NEWSR]`
 
            - `2 digits` for the year
            - `2 alphanumeric characters` for the sequence number of the voyage
            - `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip).

          pattern: ^\d{2}[0-9A-Z]{2}[NEWSR]$
          minLength: 5
          maxLength: 5
          example: 2103N
        universalImportVoyageReference:
          type: string
          description: |
            A global unique voyage reference for the import Voyage, as per DCSA standard, agreed by VSA partners for the voyage.The voyage reference must match the regular expression pattern: `\d{2}[0-9A-Z]{2}[NEWSR]`
 
            - `2 digits` for the year
            - `2 alphanumeric characters` for the sequence number of the voyage
            - `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip).

          pattern: ^\d{2}[0-9A-Z]{2}[NEWSR]$
          minLength: 5
          maxLength: 5
          example: 2103N
        barge:
          $ref: '#/components/schemas/Barge'
    OtherTransport:
      title: Other Transport
      type: object
      description: Other Transport modes.
      additionalProperties: false
      required:
        - modeOfTransport
      properties:
        modeOfTransport:
          type: string
          description: |
            The mode of transport as defined by DCSA. The allowed values for the Other Transport mode are:
            - `RAIL` (When the transport mode is Rail)
            - `TRUCK`(When the transport mode is Truck)
            - `RAIL_TRUCK`(When rail and truck are expected to be the mode of transport in a leg of a proposed routing)
            - `BARGE_TRUCK`(When barge and truck are expected to be the mode of transport in a leg of a proposed routing)
            - `BARGE_RAIL`(When barge and rail are expected to be the mode of transport in a leg of a proposed routing)
            - `MULTIMODAL`(When mode of transport is not really defined or unknown at this stage)
          enum:
            - RAIL_TRUCK
            - BARGE_TRUCK
            - BARGE_RAIL
            - MULTIMODAL
            - RAIL
            - TRUCK
          example: RAIL
    Facility:
      title: Facility
      type: object
      description: A way to express a location using a `Facility`. The facility can either be expressed using a `BIC` code or a `SMDG` code. The `facilityCode` does not contain the `UNLocationCode` - this should be provided in the `UnLocationCode` attribute.
      required:
        - facilityCode
        - facilityCodeListProvider
      properties:
        facilityCode:
          type: string
          pattern: ^\S(?:.*\S)?$
          maxLength: 6
          example: ADT
          description: |
            The code used for identifying the specific facility. This code does not include the UN Location Code.The definition of the code depends on the `facilityCodeListProvider`. As code list providers maintain multiple codeLists the following codeList is used:
              - for `SMDG` - the codeList used is the [SMDG Terminal Code List](https://smdg.org/documents/smdg-code-lists/)
              - for `BIC`  - the codeList used is the [BIC Facility Codes](https://www.bic-code.org/facility-codes/)
        facilityCodeListProvider:
          type: string
          description: |
            The provider used for identifying the facility Code. Some facility codes are only defined in combination with an `UN Location Code`.
            - `BIC` (Requires a UN Location Code) 
            - `SMDG` (Requires a UN Location Code)
          enum:
            - BIC
            - SMDG
          example: SMDG
    ServicePartner:
      title: Service Partner
      type: object
      description: The service code and voyage number as identified by the carriers that are partners in the service.
      properties:
        carrierCode:
          type: string
          description: The carrier code based on either the SMDG or SCAC code lists.
          maxLength: 4
          pattern: ^\S+$
          example: MAEU
        carrierCodeListProvider:
          type: string
          description: |
            Identifies the code list provider used for the `carrierCode`.
            - `SMDG` (Ship Message Design Group)
            - `NMFTA` (National Motor Freight Traffic Association)
          example: NMFTA
          enum:
            - SMDG
            - NMFTA
        carrierServiceName:
          type: string
          description: The name of the service.
          maxLength: 50
          pattern: ^\S(?:.*\S)?$
          example: Great Lion Service
        carrierServiceCode:
          type: string
          description: The carrier-specific code of the service for which the schedule details are published.
          maxLength: 11
          example: FE1
          pattern: ^\S(?:.*\S)?$
        carrierImportVoyageNumber:
          type: string
          maxLength: 50
          pattern: ^\S(?:.*\S)?$
          example: 2103S
          description: The identifier of an import voyage. The carrier-specific identifier of the import Voyage.
        carrierExportVoyageNumber:
          type: string
          example: 2103N
          maxLength: 50
          pattern: ^\S(?:.*\S)?$
          description: The identifier of an export voyage. The carrier-specific identifier of the export Voyage.
    ServicePartnerSchedule:
      title: Service Partner Schedule
      type: object
      required:
        - carrierServiceName
        - carrierServiceCode
        - carrierImportVoyageNumber
        - carrierExportVoyageNumber
      description: The service code and voyage number as identified by the carriers that are partners in the service.
      properties:
        carrierCode:
          type: string
          description: The carrier code based on either the SMDG or SCAC code lists.
          maxLength: 4
          pattern: ^\S+$
          example: MAEU
        carrierCodeListProvider:
          type: string
          description: |
            Identifies the code list provider used for the `carrierCode`.
            - `SMDG` (Ship Message Design Group)
            - `NMFTA` (National Motor Freight Traffic Association)
          example: NMFTA
          enum:
            - SMDG
            - NMFTA
        carrierServiceName:
          type: string
          description: The name of the service.
          maxLength: 50
          pattern: ^\S(?:.*\S)?$
          example: Great Lion Service
        carrierServiceCode:
          type: string
          description: The carrier-specific code of the service for which the schedule details are published.
          maxLength: 11
          example: FE1
          pattern: ^\S(?:.*\S)?$
        carrierImportVoyageNumber:
          type: string
          maxLength: 50
          pattern: ^\S(?:.*\S)?$
          example: 2103S
          description: The identifier of an import voyage. The carrier-specific identifier of the import Voyage.
        carrierExportVoyageNumber:
          type: string
          example: 2103N
          maxLength: 50
          pattern: ^\S(?:.*\S)?$
          description: The identifier of an export voyage. The carrier-specific identifier of the export Voyage.

    IntermediateCall:
      title: Intermediate Call
      type: object
      description: |
        An intermediate call between `departure` and `arrival` in the current leg. 

        The cargo remains on the same planned transport, and no transhipment takes place at this location.
      properties:
        transportCallReference:
          type: string
          example: SR11111X-9321483-2107W-NLAMS-ACT-1-1
          maxLength: 100
          description: |
            The unique reference for the arrival transport call. It's the vessel operator's responsibility to provide the Transport Call Reference, other parties are obliged to pick it up and use it. It can take the form of Port Call References as defined in OVS Definitions Document, or alternatively a reference as defined by the vessel operator.
        facilityTypeCode:
          description: |
            The code to identify the specific type of facility. The code indicates which role the facility plays during the transportCall.
            - `BORD` (Border)
            - `CLOC` (Customer Location)
            - `COFS` (Container Freight Station)
            - `OFFD` (Off Dock Storage)
            - `DEPO` (Depot)
            - `INTE` (Inland Terminal)
            - `POTE` (Port Terminal)
            - `PBPL` (Pilot Boarding Place)
            - `BRTH` (Berth)
            - `RAMP` (Ramp)
            - `WAYP` (Waypoint)
          example: POTE
          maxLength: 4
          type: string
        location:
          $ref: '#/components/schemas/Location'
        arrivalDateTime:
          type: string
          format: date-time
          example: '2025-01-14T09:21:00+01:00'
          description: The local date and time, when the arrival will take place.
        departureDateTime:
          type: string
          format: date-time
          example: '2025-01-14T09:21:00+01:00'
          description: The local date and time, when the departure will take place.
      required:
        - location

    Leg:
      title: Leg
      type: object
      description: Leg of the Point-to-Point routing. The property `Leg` can be conformed by as many leg as needed and this leg must be identified with a sequence number.
      required:
        - departure
        - arrival
      properties:
        sequenceNumber:
          type: integer
          format: int32
          description: Sequence number of the leg.
          example: 1
        transport:
          description: The mode of transport as defined by DCSA.
          oneOf:
            - $ref: '#/components/schemas/VesselTransport'
            - $ref: '#/components/schemas/BargeTransport'
            - $ref: '#/components/schemas/OtherTransport'
        departure:
          $ref: '#/components/schemas/PlaceOfDeparture'
        intermediateCalls:
          type: array
          description: |
            The option to list all intermediate calls between `departure` and `arrival`.

            Intermediate calls are calls where no transhipment and no change of mode of transport takes place.

            This structure allows intermediate non-transhipment calls to be grouped under a single leg, enabling consumers to present them as collapsed or expanded elements in the user interface, instead of treating each call as a separate leg.

            The list only includes calls taking place **between** the `departure` and `arrival` of the current leg.

            The order of the list is the order of visits from `departure` to `arrival`.
          items:
            $ref: '#/components/schemas/IntermediateCall'
        arrival:
          $ref: '#/components/schemas/PlaceOfArrival'
        footprint:
          type: object
          description: |
            Estimated footprint emission values for this particular leg.
          properties:
            co2:
              type: number
              format: double
              description: |
                CO<sub>2</sub> (Carbon Dioxide) emissions in metric tonnes (t).
              example: 506.4
            co2e:
              type: number
              format: double
              description: |
                CO<sub>2</sub>e (Carbon Dioxide equivalent) emissions in metric tonnes (t).
              example: 520.7
            sox:
              type: number
              format: double
              description: |
                SO<sub>x</sub> (Sulphur Oxide) emissions in kilograms (kg).
              example: 12.4
            nox:
              type: number
              format: double
              description: |
                NO<sub>x</sub> (Nitrogen Oxide) emissions in kilograms (kg).
              example: 15.4
            pm10:
              type: number
              format: double
              description: |
                PM<sub>10</sub> (Small Particle) emissions in kilograms (kg).
              example: 0.8
        cutOffTimes:
          type: array
          description: A list of cut-offs times provided by the carrier when available for this particular leg. A cut-off time indicates the latest date and time by which a task must be completed. For example, the latest date and time by which certain documentation must be provided by the Shipper.
          items:
            $ref: '#/components/schemas/CutOffTime'
    Location:
      title: Location
      type: object
      description: |
        The location can be specified using **any** of the nested structures:
          - `address` (used to specify the location via a **structured** Address)
          - `addressLines` (used to specify a location via an **unstructured** Address)
          - `UNLocationCode`
          - `Facility` (used to specify a location using a `facilityCode` and a `facilityCodeListProvider`)

          It is expected that if a location is specified in multiple ways (both as an `Address` and as a `Facility`) that both ways point to the same location.

          **Condition:** Providers **or** consumers on API v1.0.1 (or earlier): `addressLines` cannot be used as the only property to identify the location.
      properties:
        locationName:
          type: string
          pattern: ^\S(?:.*\S)?$
          example: Port of Amsterdam
          maxLength: 100
          description: An optional name for the location.
        facilityName:
          maxLength: 100
          type: string
          description: The name of the facility.
          example: Building 123
        address:
          $ref: '#/components/schemas/Address'
        addressLines:
          type: array
          maxItems: 5
          description: |
            Unstructured address lines, used as a fallback when structured address fields are unavailable.

            **Condition:** Providers **or** consumers on API v1.0.1 (or earlier): `addressLines` cannot be used as the only property to identify the location.
          items:
            type: string
            maxLength: 250
            description: |
              One line of an unstructured `Address`.
            example: "123 Example Rd"
        UNLocationCode:
          type: string
          pattern: ^[A-Z]{2}[A-Z2-9]{3}$
          minLength: 5
          maxLength: 5
          description: |
            The UN Location code specifying where the place is located. The pattern used must be

            - 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)
            - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used

            More info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)
          example: NLAMS
        facility:
          $ref: '#/components/schemas/Facility'
    TransportCallLocation:
      title: TransportCall Location
      type: object
      description: |
        General purpose object to capture location-related data, the location can be specified in **any** of the following ways:
          - `address` (used to specify the location via a **structured** Address)
          - `addressLines` (used to specify a location via an **unstructured** Address)
          - `UNLocationCode`
          - `FacilitySMDGCode` (used to specify a location using a `facilitySMDGCode`)

          It is expected that if a location is specified in multiple ways (both as an `Address` and as a `Facility`) that both ways point to the same location.

          **Condition:** Providers **or** consumers on API v1.0.1 (or earlier): `addressLines` cannot be used as the only property to identify the location.
      properties:
        locationName:
          type: string
          pattern: ^\S(?:.*\S)?$
          example: Port of Amsterdam
          maxLength: 100
          description: An optional name for the location.
        facilityName:
          maxLength: 100
          type: string
          description: The name of the facility.
          example: Building 123
        address:
          $ref: '#/components/schemas/Address'
        addressLines:
          type: array
          maxItems: 5
          description: |
            Unstructured address lines, used as a fallback when structured address fields are unavailable.

            **Condition:** Providers **or** consumers on API v1.0.1 (or earlier): `addressLines` cannot be used as the only property to identify the location.
          items:
            type: string
            maxLength: 250
            description: |
              One line of an unstructured `Address`.
            example: "123 Example Rd"
        UNLocationCode:
          type: string
          pattern: ^[A-Z]{2}[A-Z2-9]{3}$
          minLength: 5
          maxLength: 5
          description: |
            The UN Location code specifying where the place is located. The pattern used must be
            
              - 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)
              - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used

              More info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)
          example: NLAMS
        facilitySMDGCode:
          type: string
          example: ACT
          description: The code used for identifying the specific facility. This code does not include the UN Location Code.
          
            The codeList used by SMDG is the [SMDG Terminal Code List](https://smdg.org/documents/smdg-code-lists/)
          maxLength: 6
    PortScheduleLocation:
      title: Port Schedule Location
      type: object
      description: |
        General purpose object to capture location-related data, the location can be specified in **any** of the following ways:
          - `UNLocationCode`
          - `FacilitySMDGCode` (used to specify a location using a `facilitySMDGCode`)

          It is expected that if a location is specified in multiple ways (both as a `UNLocationCode` and as a `facilitySMDGCode`) that both ways point to the same location.
      properties:
        locationName:
          type: string
          pattern: ^\S(?:.*\S)?$
          example: Port of Amsterdam
          maxLength: 100
          description: An optional name for the location.
        facilityName:
          maxLength: 100
          type: string
          description: The name of the facility.
          example: Building 123
        UNLocationCode:
          type: string
          pattern: ^[A-Z]{2}[A-Z2-9]{3}$
          minLength: 5
          maxLength: 5
          description: |
            The UN Location code specifying where the place is located. The pattern used must be
            
              - 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)
              - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used

              More info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)
          example: NLAMS
        facilitySMDGCode:
          type: string
          example: ACT
          description: The code used for identifying the specific facility. This code does not include the UN Location Code.
          
            The codeList used by SMDG is the [SMDG Terminal Code List](https://smdg.org/documents/smdg-code-lists/)
          maxLength: 6
    DetailedError:
      title: Detailed Error
      type: object
      description: A detailed description of what has caused the error.
      required:
        - errorCodeText
        - errorCodeMessage
      properties:
        errorCode:
          type: integer
          format: int32
          description: |
            The detailed error code returned. The codes returned are maintained by the implementor of the API. For further explanation as to the meaning of an errorCode please consult the implementer.

            **Note:** Previously it was the intention of DCSA to standardize this but it never gained traction.
          example: 7003
          minimum: 7000
          maximum: 9999
        property:
          type: string
          description: The name of the property causing the error.
          example: facilityCode
          maxLength: 100
        value:
          type: string
          description: The value of the property causing the error serialised as a string exactly as in the original request.
          example: SG SIN WHS
          maxLength: 500
        jsonPath:
          type: string
          description: A path to the property causing the error, formatted according to [JSONpath](https://github.com/json-path/JsonPath).
          example: $.location.facilityCode
          maxLength: 500
        errorCodeText:
          type: string
          description: A standard short description corresponding to the `errorCode`.
          example: invalidData
          maxLength: 100
        errorCodeMessage:
          type: string
          description: A long description corresponding to the `errorCode` with additional information.
          example: Spaces not allowed in facility code
          maxLength: 5000
  parameters:
    Api-Version-Major:
      in: header
      name: API-Version
      required: false
      schema:
        type: string
        example: '1'
      description: |
        An API-Version header **MAY** be added to the request (optional); if added it **MUST** only contain **MAJOR** version. API-Version header **MUST** be aligned with the URI version.
tags:
  - name: Point To Point
    description: ' '
  - name: Port Schedule
    description: ' '
  - name: Vessel Schedule
    description: ' '