Commercial Schedules 1.0

Standard documentation

Standard Documentation Page | Commercial Schedules 1.0
Overview1. Introduction2. User Stories3. Use cases4. Diagrams5. Data overview per use case and endpoint
Visit the DCSA OpenAPI specification for Commercial Schedules for a detailed data overview, query parameters and response body per endpoint.

5.1 - Commercial schedules – point to point routing

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 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.Visit the endpoint below for a detailed overview data overview, query parameters and response body.
Visit the endpoint
5.1.1 - Request parameters & response bodyThe 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.

5.2 - Commercial schedules – port schedule

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 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.Visit the endpoint for a detailed overview data overview, query parameters and response body.
Visit the endpoint
5.2.1 - Request parameters & response bodyThe 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).

5.3 - Commercial schedules – vessel schedule

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 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.Visit the endpoint below for a detailed overview data overview, query parameters and response body.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 is used between carriers, and carriers and terminals.
Visit the endpoint
5.3.1 - Request parameters & response bodyThe 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.