Method: shipping.designShippingNetwork

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)
    }
  ]
}
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)

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.

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.

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.

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: 7 hourOfDay: 12 } } These legs define a one-week service lines going through two ports with both port stay times of 12 hours.

JSON representation 
{
  "vesselClassId": string,
  "vesselServiceLegs": [
    {
      object (VesselServiceLeg)
    }
  ]
}
Fields
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.

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
}
Fields
vesselServiceIndex

integer

Index of the vessel service.
vesselServiceLegIndex

integer

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