Method: shipping.designShippingNetwork

  • The Liner Shipping Network Design and Scheduling Problem (LSNDSP) API optimizes shipping networks to minimize costs and maximize revenue by determining the best port selection, vessel deployment, and scheduling.

  • The API receives input data on ports, routes, vessels, cargo demands, and existing services, then uses optimization algorithms to design a cost-effective network configuration.

  • Outputs include optimized vessel service schedules and commodity demand paths, detailing how cargo is routed to meet demands while adhering to constraints like vessel capacity.

  • Commodity demand paths are constructed using vessel service leg IDs, ensuring cargo is transferred efficiently between different services and ports to reach its final destination within the allowed transit time.

  • The API allows for specifying solver parameters, enabling users to control aspects of the optimization process.

Solves the liner shipping network design and scheduling problem (LSNDSP) from the given DesignShippingNetworkRequest.

The LSNDSP is a complex optimization problem that seeks to find the optimal design and scheduling of a liner shipping network. The goal is to minimize the total cost of operating the network, while meeting as much of the cargo demand between ports as possible.

The LSNDSP can be broken down into two main subproblems: network design and scheduling. The network design subproblem determines the set of ports to be served by the network, the number of vessels to be deployed on each route, and the routes that the vessels will take. The scheduling subproblem determines the sailing schedules for the vessels, taking into account the time it takes to sail between ports, the time it takes to load and unload cargo, and the demand for cargo transportation between ports.

In simple words, the LSNDSP is the problem of deciding which ports to serve, how many ships to use, and how to schedule the ships so that the cost of operating the network is minimized while maximizing the revenue for fulfilling cargo demand. A challenging subcomponent of the LSNDSP is the cargo routing, which determines which demands to meet and which routes to assign to cargo in order to maximize revenue.

HTTP request

POST https://optimization.googleapis.com/v1/shipping:designShippingNetwork

The URL uses gRPC Transcoding syntax.

Request body

The request body contains data with the following structure:

JSON representation 
{
  "requestId": string,
  "solverParameters": {
    object (SolverParameters)
  },
  "ports": [
    {
      object (Port)
    }
  ],
  "legCandidates": [
    {
      object (LegCandidate)
    }
  ],
  "vesselClasses": [
    {
      object (VesselClass)
    }
  ],
  "commodityDemands": [
    {
      object (CommodityDemand)
    }
  ],
  "vesselServices": [
    {
      object (VesselService)
    }
  ],
  "vesselServiceConstraints": [
    {
      object (VesselServiceConstraint)
    }
  ]
}
Fields
requestId

string

Problem or request ID.
solverParameters

object (SolverParameters)

Parameters for the solver.
ports[]

object (Port)

List of possible ports to be called in vessel services. The request must only contain port IDs that are in this list.
legCandidates[]

object (LegCandidate)

List of potential leg candidates to be added to vessel services. The request must only contain leg candidate IDs that are in this list.
vesselClasses[]

object (VesselClass)

List of vessel classes to perform vessel services. Note that all vessels from the same class are completely interchangeable. The request must only contain vessel class IDs that are in this list.
commodityDemands[]

object (CommodityDemand)

List of potential commodity (i.e. container) demands to be fulfilled by vessel services.
vesselServices[]

object (VesselService)

Optional. A network of valid vessel services (typically the current state of the network) can be provided to be used as a starting point for the optimization. These services must be valid on their own and also adhere to any constraints specified in the vesselServiceConstraints field.
vesselServiceConstraints[]

object (VesselServiceConstraint)

Optional. Fixing constraints for vessel services. Each constraint must refer to a vessel service from the vesselServices field via vesselServiceId. The input VesselService MUST already satisfy the constraints defined in the corresponding VesselServiceConstraint. If there is an entry for a vessel service, that service is not allowed to be removed from the network.

Response body

The response holds the solution to the LSNDSP instance passed in the request. It contains a valid network of vessel services and commodity demand paths. The total commodity demand going through each leg cannot exceed the vessel class capacity serving this leg. Note that having no vessel services with no fulfilled demand is always a feasible solution to the liner shipping network design and scheduling problem.

If successful, the response body contains data with the following structure:

JSON representation 
{
  "requestId": string,
  "vesselServices": [
    {
      object (VesselService)
    }
  ],
  "commodityDemandPaths": [
    {
      object (CommodityDemandPath)
    }
  ]
}
Fields
requestId

string

The ID of the request that this response is associated with.
vesselServices[]

object (VesselService)

Network of vessel services. For each vessel class, the total number of vessels used cannot exceed the available number of vessels for this class.
commodityDemandPaths[]

object (CommodityDemandPath)

List of all commodity demand paths through which positive commodity demand are shipped. Note that some commodity demand IDs might not be included if no demand is shipped. Alternatively, a commodity demand can be partially fulfilled. For each commodity demand, the total fulfilled quantity cannot exceed the total demand. Finally, commodityDemandPaths depend on vesselServices (see CommodityDemandPath definition).

SolverParameters

Parameters that control a single solve of the LSNDSP.

JSON representation 
{
  "timeLimit": string
}
Fields
timeLimit

string (Duration format)

Maximum time the solver should spend on the problem. This value is not a hard limit and it does not account for the communication overhead. The expected latency to solve the problem may slightly exceed this value.

A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".

Port

Port, e.g. a terminal or all terminals of a port.

JSON representation 
{
  "id": string,
  "minimumPortStayDuration": {
    object (Duration)
  },
  "minimumTransshipmentDuration": {
    object (Duration)
  },
  "transshipmentCost": number,
  "vesselClassCosts": {
    string: {
      object (VesselCost)
    },
    ...
  }
}
Fields
id

string

Unique ID assigned to this port.
minimumPortStayDuration

object (Duration)

Minimum duration of stay for a port call. Most studies assume constant as ports typically assign more cranes to larger vessels with high move counts, as they take up more space.
minimumTransshipmentDuration

object (Duration)

Minimum duration of a transshipment at a given port, including duration to unload a container and reload it onto another vessel.
transshipmentCost

number

Cost of transshipping a container. It will usually be lower than the sum of loading and discharging because transshipping does not require customs paperwork at the port.
vesselClassCosts

map (key: string, value: object (VesselCost))

Costs incurred when calling this port mapped by vessel class ID. A vessel class can only call this port if it has an entry in this map.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

Duration

A duration (port stay/transshipment, demand transit) is defined on an hourly granularity and must be positive.

JSON representation 
{
  "hours": string
}
Fields
hours

string (int64 format)

Number of hours defining the duration.

VesselCost

Vessel cost for calling and staying at this port is defined as a linear function of the stay duration (fixedCost + hourlyCost * hours).

JSON representation 
{
  "fixedCost": number,
  "hourlyCost": number
}
Fields
fixedCost

number

Fixed cost for calling this port.
hourlyCost

number

Hourly cost for staying at this port.

LegCandidate

Vessel service leg candidate. There can be multiple leg candidates between the same two ports, e.g. representing different ocean routes and/or vessel velocities. However, there can only be one leg candidate between two ports with a given duration.

JSON representation 
{
  "id": string,
  "departurePortId": string,
  "arrivalPortId": string,
  "duration": {
    object (Duration)
  },
  "vesselClassCosts": {
    string: number,
    ...
  }
}
Fields
id

string

Unique ID assigned to this leg candidate.
departurePortId

string

ID of the departure port.
arrivalPortId

string

ID of the arrival port.
duration

object (Duration)

Duration of the leg.
vesselClassCosts

map (key: string, value: number)

Cost for assigning this leg candidate to a certain vessel class. This can include vessel operating cost, bunker cost, charter cost. A vessel class can only sail though this leg candidate if it has an entry in this map.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

VesselClass

Vessel class, i.e., a group of vessel(s) sharing the same properties. There is no way to differentiate between two vessels from the same class.

JSON representation 
{
  "id": string,
  "containerCapacity": string,
  "vesselCount": string
}
Fields
id

string

Unique ID assigned to this vessel class.
containerCapacity

string (int64 format)

Vessel class capacity (in containers).
vesselCount

string (int64 format)

Number of vessels in this vessel class.

CommodityDemand

Commodity demand, i.e., a potential demand to be fulfilled by a shipper.

JSON representation 
{
  "id": string,
  "originPortId": string,
  "destinationPortId": string,
  "containerCount": string,
  "freightRate": number,
  "maximumTransitDuration": {
    object (Duration)
  }
}
Fields
id

string

Unique ID assigned to this commodity demand.
originPortId

string

ID of the origin port.
destinationPortId

string

ID of the destination port.
containerCount

string (int64 format)

Maximum number of containers to be fulfilled.
freightRate

number

Freight rate per container (which could include a penalty for unfulfilled demand). It should remove the cost of loading and discharging per container at origin and destination.
maximumTransitDuration

object (Duration)

Maximum transit duration (if set, should be stricly positive). Transit time is defined from the time when the first vessel serving this demand leaves the origin port to the time when the last vessel serving this demand arrives at the destination port.

VesselService

Vessel service which can be used to serve commodity demands. IMPORTANT: a current assumption is that services are on a weekly frequency and port stay times cannot exceed one week. Consider the following sequence of vessel service legs: vesselServiceLegs { legCandidateId: "0->1" originDepartureTime {} destinationArrivalTime { day: 3 hourOfDay: 12 } } vesselServiceLegs { legCandidateId: "1->0" originDepartureTime { day: 4 } destinationArrivalTime { day: 6 hourOfDay: 12 } } These legs define a one-week service lines going through two ports with both port stay times of 12 hours.

JSON representation 
{
  "id": string,
  "vesselClassId": string,
  "vesselServiceLegs": [
    {
      object (VesselServiceLeg)
    }
  ]
}
Fields
id

string

Unique ID assigned to this vessel service.
vesselClassId

string

Vessel class ID performing the service.
vesselServiceLegs[]

object (VesselServiceLeg)

For a valid vessel service, the following properties hold: 1. It cannot be empty. 2. Consecutive legs' destinationPortId and originPortId must match (including for the last and first legs).

VesselServiceLeg

A single leg of a vessel service.

JSON representation 
{
  "legCandidateId": string,
  "originDepartureTime": {
    object (ScheduleTime)
  },
  "destinationArrivalTime": {
    object (ScheduleTime)
  }
}
Fields
legCandidateId

string

Assigned leg candidate ID.
originDepartureTime

object (ScheduleTime)

Time of departure at the origin port on the weekly schedule.
destinationArrivalTime

object (ScheduleTime)

Time of arrival at the destination port on the weekly schedule.

ScheduleTime

A schedule time (vessel/demand departure/arrivals) is defined on a weekly frequency at a given hour.

JSON representation 
{
  "day": string,
  "hourOfDay": integer
}
Fields
day

string (int64 format)

Day on the schedule. Day 0 is the first possible day.
hourOfDay

integer

Hour of day of the schedule time should be an integer between 0 and 23 inclusive.

VesselServiceConstraint

Defines the level of fixing for a vessel service. This can be used to control which parts of the service are fixed and which can be optimized. The enforcement of such constraint on a service implies it cannot be removed.

JSON representation 
{
  "vesselServiceId": string,
  "allowedVesselClassIds": [
    string
  ],
  "minimumVesselCount": integer,
  "maximumVesselCount": integer,
  "portSequenceConstraint": {
    object (PortSequenceConstraint)
  }
}
Fields
vesselServiceId

string

Required. The ID of the vessel service to which this constraint applies. This must correspond to the ID of a VesselService in the vesselServices field of the DesignShippingNetworkRequest.
allowedVesselClassIds[]

string

Optional. The list of vessel class IDs that are permitted for this service. If empty, any vessel class can be assigned.
minimumVesselCount

integer

Optional. Minimum number of vessels (i.e. weeks) that the service must have. If not set, there is no lower bound.
maximumVesselCount

integer

Optional. Maximum number of vessels (i.e. weeks) that the service must have. If not set, there is no upper bound. If set, must be greater than or equal to minimumVesselCount.
portSequenceConstraint

object (PortSequenceConstraint)

Optional. If set, the sequence of ports is fixed according to the settings within PortSequenceConstraint. The port sequence itself is taken from the corresponding VesselService in the request.

PortSequenceConstraint

Settings for fixing the port sequence and optionally the schedule.

JSON representation 
{
  "maximumScheduleTimeDeviation": {
    object (Duration)
  }
}
Fields
maximumScheduleTimeDeviation

object (Duration)

Optional. Maximum allowed deviation (both earlier and later) for each arrival and departure time on the service's weekly schedule, relative to the time specified in the corresponding leg of the input VesselService. For an original weekly schedule time T (e.g., Wednesday 10:00), a maximumScheduleTimeDeviation of D means the event in the optimized schedule must occur within the time interval [T - D, T + D] (modulo one week).

Example: If the original time is Wednesday 08:00 and maximumScheduleTimeDeviation is { hours: 24 }, the new time must be between Tuesday 08:00 and Thursday 08:00 inclusive.

If this field is not set, the schedule is fully flexible, even though the port sequence is fixed. The deviation duration value must be non-negative and less than one week (168 hours).

CommodityDemandPath

The different services and ports that a fraction of a given commodity demand is taking. Indices used below are based on the order of vessel services in the response and the order of service legs in individual vessel services.

JSON representation 
{
  "commodityDemandId": string,
  "containerCount": string,
  "vesselServiceLegIds": [
    {
      object (VesselServiceLegId)
    }
  ]
}
Fields
commodityDemandId

string

Commodity demand ID fulfilled.
containerCount

string (int64 format)

Number of containers going through this path. For each commodity demand, the total fulfilled quantity cannot exceed the total demand.
vesselServiceLegIds[]

object (VesselServiceLegId)

List of vessel service leg IDs taken through this path. For a valid commodity demand path, the following properties hold: 1. First leg's departurePortId must match originPortId of the commodity demand. 2. Last leg's destinationPortId must match destinationPortId of the commodity demand. 3. Consecutive legs' arrivalPortId and departurePortId must match. 4. If provided for this commodity demand, the maximum transit time should be greater or equal than the total duration of the path.

VesselServiceLegId

Single vessel service leg used in a commodity demand path. For instance, consider that there are two vessel services. The first is made of three legs (indexed 0, 1 and 2) and the second two (indexed 0 and 1). In addition, the first leg of the first service arrives at the departure port of the second leg of the second service. A commodity path consisting of the three following vessel service leg ids: {vesselServiceIndex: 0, vesselServiceLegIndex: 2} {vesselServiceIndex: 0, vesselServiceLegIndex: 0} {vesselServiceIndex: 1, vesselServiceLegIndex: 1} means that containers take 2 consecutive legs from the first vessel service (note that 2 and 0 are consecutive since each service is a cycle), then transships to vessel service 1 for a single leg.

JSON representation 
{
  "vesselServiceIndex": integer,
  "vesselServiceLegIndex": integer,
  "vesselServiceId": string
}
Fields
vesselServiceIndex

integer

Index of the vessel service.
vesselServiceLegIndex

integer

Index of the leg from the vessel service indexed by vesselServiceIndex.
vesselServiceId

string

Optional. The ID of the vessel service. This is set if and only if the service was part of the input request.