Create or update a plan's resource

Error

A valid request URL is required to generate request examples

{
  "item": {
    "id": "<string>",
    "vehicleProfile": {
      "type": "fly",
      "kmph": 123
    },
    "workingTimeWindow": {
      "begin": "2019-11-15T12:34:56Z",
      "end": "2019-11-15T12:34:56Z"
    },
    "properties": {},
    "state": {
      "mode": "free",
      "assignments": [
        {
          "stopId": "<string>",
          "type": "stop",
          "status": "fixed",
          "arrivalTime": "2019-11-15T12:34:56Z",
          "beginTime": "2019-11-15T12:34:56Z",
          "departureTime": "2019-11-15T12:34:56Z"
        }
      ]
    },
    "cost": {
      "workedHours": {
        "constantCost": 123,
        "costFloor": 123,
        "costCoeff": 123,
        "overcostFloor": 123,
        "overcostCoeff": 123
      },
      "km": {
        "constantCost": 123,
        "costFloor": 123,
        "costCoeff": 123,
        "overcostFloor": 123,
        "overcostCoeff": 123
      },
      "using": 123,
      "costsByStopTag": {},
      "costsByCapacity": {},
      "costPerCapacityPerTravelledKm": {
        "weight": {
          "costCoeff": 0.2
        },
        "volume": {
          "costCoeff": 0.1
        }
      },
      "costPerCapacityPerTravelledHour": {
        "weight": {
          "costCoeff": 0.05
        }
      }
    },
    "CO2EmissionCalculation": {
      "km": {
        "costCoeff": 0.55
      },
      "costPerCapacityPerTravelledKm": {
        "weight": {
          "costCoeff": 0.2
        }
      },
      "costPerCapacityPerTravelledHour": {
        "weight": {
          "costCoeff": 0.05
        }
      }
    },
    "priority": 0,
    "skills": [
      "forklift",
      "truck"
    ],
    "preferredStopTags": [
      "access:parking33",
      "capa:bat22",
      "setup:france"
    ],
    "tags": [
      "trailer"
    ],
    "capacities": {
      "volume": 9.5,
      "weight": 2200,
      "nbPackages": 23
    },
    "departure": {
      "lon": 2.3269331,
      "lat": 48.8812658
    },
    "arrival": {
      "lon": 2.3269331,
      "lat": 48.8812658
    },
    "maxWorkingDuration": "PT4M",
    "maxDistanceInKm": 123,
    "maxInterStopDistanceInKm": 50,
    "maxInterStopDuration": "PT4M",
    "breaks": [
      {
        "duration": "PT4M",
        "timeWindow": {
          "begin": "2019-11-15T12:34:56Z",
          "end": "2019-11-15T12:34:56Z"
        },
        "type": "timeWindowBreak"
      }
    ],
    "operationDurationPolicies": [
      {
        "stopTags": [
          "access:parking33",
          "capa:bat22",
          "setup:france"
        ]
      }
    ],
    "travelTimeCoefficient": 1.05,
    "emptyThresholdByCapacity": {
      "volume": 50,
      "weight": 100,
      "nbPackages": 23
    },
    "avoidEarlyLoadings": [
      {
        "stopTag": "depot1",
        "capacities": [
          "weight",
          "volume"
        ]
      }
    ]
  },
  "agencyId": "LND_Agency-42",
  "planId": "plan-AB",
  "planVersion": 42
}

{
  "item": {
    "id": "<string>",
    "vehicleProfile": {
      "type": "fly",
      "kmph": 123
    },
    "workingTimeWindow": {
      "begin": "2019-11-15T12:34:56Z",
      "end": "2019-11-15T12:34:56Z"
    },
    "properties": {},
    "state": {
      "mode": "free",
      "assignments": [
        {
          "stopId": "<string>",
          "type": "stop",
          "status": "fixed",
          "arrivalTime": "2019-11-15T12:34:56Z",
          "beginTime": "2019-11-15T12:34:56Z",
          "departureTime": "2019-11-15T12:34:56Z"
        }
      ]
    },
    "cost": {
      "workedHours": {
        "constantCost": 123,
        "costFloor": 123,
        "costCoeff": 123,
        "overcostFloor": 123,
        "overcostCoeff": 123
      },
      "km": {
        "constantCost": 123,
        "costFloor": 123,
        "costCoeff": 123,
        "overcostFloor": 123,
        "overcostCoeff": 123
      },
      "using": 123,
      "costsByStopTag": {},
      "costsByCapacity": {},
      "costPerCapacityPerTravelledKm": {
        "weight": {
          "costCoeff": 0.2
        },
        "volume": {
          "costCoeff": 0.1
        }
      },
      "costPerCapacityPerTravelledHour": {
        "weight": {
          "costCoeff": 0.05
        }
      }
    },
    "CO2EmissionCalculation": {
      "km": {
        "costCoeff": 0.55
      },
      "costPerCapacityPerTravelledKm": {
        "weight": {
          "costCoeff": 0.2
        }
      },
      "costPerCapacityPerTravelledHour": {
        "weight": {
          "costCoeff": 0.05
        }
      }
    },
    "priority": 0,
    "skills": [
      "forklift",
      "truck"
    ],
    "preferredStopTags": [
      "access:parking33",
      "capa:bat22",
      "setup:france"
    ],
    "tags": [
      "trailer"
    ],
    "capacities": {
      "volume": 9.5,
      "weight": 2200,
      "nbPackages": 23
    },
    "departure": {
      "lon": 2.3269331,
      "lat": 48.8812658
    },
    "arrival": {
      "lon": 2.3269331,
      "lat": 48.8812658
    },
    "maxWorkingDuration": "PT4M",
    "maxDistanceInKm": 123,
    "maxInterStopDistanceInKm": 50,
    "maxInterStopDuration": "PT4M",
    "breaks": [
      {
        "duration": "PT4M",
        "timeWindow": {
          "begin": "2019-11-15T12:34:56Z",
          "end": "2019-11-15T12:34:56Z"
        },
        "type": "timeWindowBreak"
      }
    ],
    "operationDurationPolicies": [
      {
        "stopTags": [
          "access:parking33",
          "capa:bat22",
          "setup:france"
        ]
      }
    ],
    "travelTimeCoefficient": 1.05,
    "emptyThresholdByCapacity": {
      "volume": 50,
      "weight": 100,
      "nbPackages": 23
    },
    "avoidEarlyLoadings": [
      {
        "stopTag": "depot1",
        "capacities": [
          "weight",
          "volume"
        ]
      }
    ]
  },
  "agencyId": "LND_Agency-42",
  "planId": "plan-AB",
  "planVersion": 42
}

{
  "errors": [
    {
      "code": "<string>",
      "message": "<string>",
      "properties": {}
    }
  ]
}

{
  "errors": [
    {
      "code": "<string>",
      "message": "<string>",
      "properties": {}
    }
  ]
}

{
  "errors": [
    {
      "code": "<string>",
      "message": "<string>",
      "properties": {}
    }
  ]
}

{
  "errors": [
    {
      "code": "<string>",
      "message": "<string>",
      "properties": {}
    }
  ]
}

{
  "errors": [
    {
      "code": "<string>",
      "message": "<string>",
      "properties": {}
    }
  ]
}

PUT

agencies

{agencyId}

plans

{planId}

resources

{resourceId}

Error

A valid request URL is required to generate request examples

{
  "item": {
    "id": "<string>",
    "vehicleProfile": {
      "type": "fly",
      "kmph": 123
    },
    "workingTimeWindow": {
      "begin": "2019-11-15T12:34:56Z",
      "end": "2019-11-15T12:34:56Z"
    },
    "properties": {},
    "state": {
      "mode": "free",
      "assignments": [
        {
          "stopId": "<string>",
          "type": "stop",
          "status": "fixed",
          "arrivalTime": "2019-11-15T12:34:56Z",
          "beginTime": "2019-11-15T12:34:56Z",
          "departureTime": "2019-11-15T12:34:56Z"
        }
      ]
    },
    "cost": {
      "workedHours": {
        "constantCost": 123,
        "costFloor": 123,
        "costCoeff": 123,
        "overcostFloor": 123,
        "overcostCoeff": 123
      },
      "km": {
        "constantCost": 123,
        "costFloor": 123,
        "costCoeff": 123,
        "overcostFloor": 123,
        "overcostCoeff": 123
      },
      "using": 123,
      "costsByStopTag": {},
      "costsByCapacity": {},
      "costPerCapacityPerTravelledKm": {
        "weight": {
          "costCoeff": 0.2
        },
        "volume": {
          "costCoeff": 0.1
        }
      },
      "costPerCapacityPerTravelledHour": {
        "weight": {
          "costCoeff": 0.05
        }
      }
    },
    "CO2EmissionCalculation": {
      "km": {
        "costCoeff": 0.55
      },
      "costPerCapacityPerTravelledKm": {
        "weight": {
          "costCoeff": 0.2
        }
      },
      "costPerCapacityPerTravelledHour": {
        "weight": {
          "costCoeff": 0.05
        }
      }
    },
    "priority": 0,
    "skills": [
      "forklift",
      "truck"
    ],
    "preferredStopTags": [
      "access:parking33",
      "capa:bat22",
      "setup:france"
    ],
    "tags": [
      "trailer"
    ],
    "capacities": {
      "volume": 9.5,
      "weight": 2200,
      "nbPackages": 23
    },
    "departure": {
      "lon": 2.3269331,
      "lat": 48.8812658
    },
    "arrival": {
      "lon": 2.3269331,
      "lat": 48.8812658
    },
    "maxWorkingDuration": "PT4M",
    "maxDistanceInKm": 123,
    "maxInterStopDistanceInKm": 50,
    "maxInterStopDuration": "PT4M",
    "breaks": [
      {
        "duration": "PT4M",
        "timeWindow": {
          "begin": "2019-11-15T12:34:56Z",
          "end": "2019-11-15T12:34:56Z"
        },
        "type": "timeWindowBreak"
      }
    ],
    "operationDurationPolicies": [
      {
        "stopTags": [
          "access:parking33",
          "capa:bat22",
          "setup:france"
        ]
      }
    ],
    "travelTimeCoefficient": 1.05,
    "emptyThresholdByCapacity": {
      "volume": 50,
      "weight": 100,
      "nbPackages": 23
    },
    "avoidEarlyLoadings": [
      {
        "stopTag": "depot1",
        "capacities": [
          "weight",
          "volume"
        ]
      }
    ]
  },
  "agencyId": "LND_Agency-42",
  "planId": "plan-AB",
  "planVersion": 42
}

{
  "item": {
    "id": "<string>",
    "vehicleProfile": {
      "type": "fly",
      "kmph": 123
    },
    "workingTimeWindow": {
      "begin": "2019-11-15T12:34:56Z",
      "end": "2019-11-15T12:34:56Z"
    },
    "properties": {},
    "state": {
      "mode": "free",
      "assignments": [
        {
          "stopId": "<string>",
          "type": "stop",
          "status": "fixed",
          "arrivalTime": "2019-11-15T12:34:56Z",
          "beginTime": "2019-11-15T12:34:56Z",
          "departureTime": "2019-11-15T12:34:56Z"
        }
      ]
    },
    "cost": {
      "workedHours": {
        "constantCost": 123,
        "costFloor": 123,
        "costCoeff": 123,
        "overcostFloor": 123,
        "overcostCoeff": 123
      },
      "km": {
        "constantCost": 123,
        "costFloor": 123,
        "costCoeff": 123,
        "overcostFloor": 123,
        "overcostCoeff": 123
      },
      "using": 123,
      "costsByStopTag": {},
      "costsByCapacity": {},
      "costPerCapacityPerTravelledKm": {
        "weight": {
          "costCoeff": 0.2
        },
        "volume": {
          "costCoeff": 0.1
        }
      },
      "costPerCapacityPerTravelledHour": {
        "weight": {
          "costCoeff": 0.05
        }
      }
    },
    "CO2EmissionCalculation": {
      "km": {
        "costCoeff": 0.55
      },
      "costPerCapacityPerTravelledKm": {
        "weight": {
          "costCoeff": 0.2
        }
      },
      "costPerCapacityPerTravelledHour": {
        "weight": {
          "costCoeff": 0.05
        }
      }
    },
    "priority": 0,
    "skills": [
      "forklift",
      "truck"
    ],
    "preferredStopTags": [
      "access:parking33",
      "capa:bat22",
      "setup:france"
    ],
    "tags": [
      "trailer"
    ],
    "capacities": {
      "volume": 9.5,
      "weight": 2200,
      "nbPackages": 23
    },
    "departure": {
      "lon": 2.3269331,
      "lat": 48.8812658
    },
    "arrival": {
      "lon": 2.3269331,
      "lat": 48.8812658
    },
    "maxWorkingDuration": "PT4M",
    "maxDistanceInKm": 123,
    "maxInterStopDistanceInKm": 50,
    "maxInterStopDuration": "PT4M",
    "breaks": [
      {
        "duration": "PT4M",
        "timeWindow": {
          "begin": "2019-11-15T12:34:56Z",
          "end": "2019-11-15T12:34:56Z"
        },
        "type": "timeWindowBreak"
      }
    ],
    "operationDurationPolicies": [
      {
        "stopTags": [
          "access:parking33",
          "capa:bat22",
          "setup:france"
        ]
      }
    ],
    "travelTimeCoefficient": 1.05,
    "emptyThresholdByCapacity": {
      "volume": 50,
      "weight": 100,
      "nbPackages": 23
    },
    "avoidEarlyLoadings": [
      {
        "stopTag": "depot1",
        "capacities": [
          "weight",
          "volume"
        ]
      }
    ]
  },
  "agencyId": "LND_Agency-42",
  "planId": "plan-AB",
  "planVersion": 42
}

{
  "errors": [
    {
      "code": "<string>",
      "message": "<string>",
      "properties": {}
    }
  ]
}

{
  "errors": [
    {
      "code": "<string>",
      "message": "<string>",
      "properties": {}
    }
  ]
}

{
  "errors": [
    {
      "code": "<string>",
      "message": "<string>",
      "properties": {}
    }
  ]
}

{
  "errors": [
    {
      "code": "<string>",
      "message": "<string>",
      "properties": {}
    }
  ]
}

{
  "errors": [
    {
      "code": "<string>",
      "message": "<string>",
      "properties": {}
    }
  ]
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

agencyId

string

required

The agency id.

Pattern: ^[A-Z]{3,6}_[a-zA-Z0-9-._~:@!$,]+$

Example:

"LND_Agency-42"

planId

string

required

The plan id. At least one character among those allowed: unaccented alpha-numeric characters, "-", ".", "_", "~", ":", "@", "!", "$", ",".

Pattern: ^[a-zA-Z0-9-._~:@!$,]+$

resourceId

string

required

The resource id. At least one character among those allowed: unaccented alpha-numeric characters, "-", ".", "_", "~", ":", "@", "!", "$", ",".

Pattern: ^[a-zA-Z0-9-._~:@!$,]+$

Query Parameters

force

boolean

default:false

If true, on an archived item, the requested action will be forced and the item will be unarchived.

Body

application/json

The Resource to update.

[TO_VALIDATE] Description pending review by a Kardinal engineer.

string

required

Resource ids must be unique within a plan.

Pattern: ^[a-zA-Z0-9-._~:@!$,]+$

vehicleProfile

object

required

Describes how this resource travels between stops: the mode of transport and its constraints. One of fly, pedestrian, bicycle, scooter, motorbike, car, or truck, each exposing different parameters (for example traffic sensitivity, weight, or hazardous goods restrictions).

Show child attributes

workingTimeWindow

object

required

The time window during which the resource is available to work. Often used together with maxWorkingDuration.

Show child attributes

properties

object

Free-form key-value pairs (strings only) with no impact on optimization, such as the driver's name. Returned unchanged in the plan and its solution.

Show child attributes

state

object

[TO_VALIDATE] Believed to describe the resource's manual-mode state (current mode and any forced stop/break assignments), used by the manual planning endpoints. Needs confirmation.

Show child attributes

cost

object

Defines a custom cost model for this resource (for example per kilometer, per capacity unit transported, or a fixed cost), used by the minimizeCosts objective. See the Cost schema below for every available cost component and its semantics.

Show child attributes

CO2EmissionCalculation

object

Optional CO2 emission calculation parameters for this resource. The object is Cost-shaped. Typical fields:

km: emission per travelled kilometre (e.g. costCoeff in g/km);
costPerCapacityPerTravelledKm: per-capacity emission per travelled kilometre;
costPerCapacityPerTravelledHour: per-capacity emission per travel hour (travel duration only). When set, the resulting emissions are reported on the tour as CO2Emission. Takes precedence over any matching plan-level declaration.

Show child attributes

Example:

{
  "km": { "costCoeff": 0.55 },
  "costPerCapacityPerTravelledKm": { "weight": { "costCoeff": 0.2 } },
  "costPerCapacityPerTravelledHour": { "weight": { "costCoeff": 0.05 } }
}

priority

integer

default:0

0 by default, can be negative.

skills

string[]

At least one character among those allowed: unaccented alpha-numeric characters, "-", ".", "_", "~", ":", "@", "!", "$", ",".

Pattern: ^[a-zA-Z0-9-._~:@!$,]+$

Example:

["forklift", "truck"]

preferredStopTags

string[]

At least one character among those allowed: unaccented alpha-numeric characters, "-", ".", "_", "~", ":", "@", "!", "$", ",".

Pattern: ^[a-zA-Z0-9-._~:@!$,]+$

Example:

[
  "access:parking33",
  "capa:bat22",
  "setup:france"
]

Response

Resource response updated.

[TO_VALIDATE] Description pending review by a Kardinal engineer.

item

object

[TO_VALIDATE] Description pending review by a Kardinal engineer.

Show child attributes

agencyId

string

The agency id.

Pattern: ^[A-Z]{3,6}_[a-zA-Z0-9-._~:@!$,]+$

Example:

"LND_Agency-42"

planId

string

The plan id.

Pattern: ^[a-zA-Z0-9-._~:@!$,]+$

Example:

"plan-AB"

planVersion

integer

read-only

The plan version.

Required range: x >= 1

Example:

42

API

Data model

Changes

Create or update a plan's resource

Authorizations

Path Parameters

Query Parameters

Body

Response