Create a simple plan

Error

A valid request URL is required to generate request examples

{
  "item": {
    "id": "cd4ce4e3-0208-4b10-b346-25f235214e4f",
    "agencyId": "LND_Agency-42",
    "resources": [
      {
        "id": "<string>",
        "workingTimeWindow": {
          "begin": "2019-11-15T12:34:56Z",
          "end": "2019-11-15T12:34:56Z"
        },
        "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,
        "breaks": [
          {
            "duration": "PT4M",
            "timeWindow": {
              "begin": "2019-11-15T12:34:56Z",
              "end": "2019-11-15T12:34:56Z"
            },
            "type": "timeWindowBreak"
          }
        ]
      }
    ],
    "version": 42,
    "nbResources": 1,
    "stops": [
      {
        "id": "<string>",
        "position": {
          "lon": 2.3269331,
          "lat": 48.8812658
        },
        "kind": "delivery",
        "operationDuration": "PT4M",
        "capacities": {
          "volume": 9.5,
          "weight": 2200,
          "nbPackages": 23
        },
        "timeWindow": {
          "begin": "2019-11-15T12:34:56Z",
          "end": "2019-11-15T12:34:56Z"
        }
      }
    ],
    "nbStops": 1,
    "objective": "minimizeResources",
    "tz": "Europe/Paris",
    "lateDeparture": false,
    "createdAt": "2019-11-15T12:34:56Z",
    "createdBy": "<string>",
    "updatedAt": "2019-11-15T12:34:56Z",
    "updatedBy": "<string>",
    "archivedAt": null
  },
  "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": {}
    }
  ]
}

POST

agencies

{agencyId}

simplePlans

Error

A valid request URL is required to generate request examples

{
  "item": {
    "id": "cd4ce4e3-0208-4b10-b346-25f235214e4f",
    "agencyId": "LND_Agency-42",
    "resources": [
      {
        "id": "<string>",
        "workingTimeWindow": {
          "begin": "2019-11-15T12:34:56Z",
          "end": "2019-11-15T12:34:56Z"
        },
        "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,
        "breaks": [
          {
            "duration": "PT4M",
            "timeWindow": {
              "begin": "2019-11-15T12:34:56Z",
              "end": "2019-11-15T12:34:56Z"
            },
            "type": "timeWindowBreak"
          }
        ]
      }
    ],
    "version": 42,
    "nbResources": 1,
    "stops": [
      {
        "id": "<string>",
        "position": {
          "lon": 2.3269331,
          "lat": 48.8812658
        },
        "kind": "delivery",
        "operationDuration": "PT4M",
        "capacities": {
          "volume": 9.5,
          "weight": 2200,
          "nbPackages": 23
        },
        "timeWindow": {
          "begin": "2019-11-15T12:34:56Z",
          "end": "2019-11-15T12:34:56Z"
        }
      }
    ],
    "nbStops": 1,
    "objective": "minimizeResources",
    "tz": "Europe/Paris",
    "lateDeparture": false,
    "createdAt": "2019-11-15T12:34:56Z",
    "createdBy": "<string>",
    "updatedAt": "2019-11-15T12:34:56Z",
    "updatedBy": "<string>",
    "archivedAt": null
  },
  "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"

Body

application/json

The SimplePlan to create.

A simple plan is a simplified representation of a plan, with simplified resources, simplified stops, and a simplified objective.

resources

object[]

required

Show child attributes

stops

object[]

Show child attributes

objective

enum<string>

default:minimizeResources

[TO_VALIDATE] Description pending review by a Kardinal engineer.

Available options:

minimizeResources,

minimizeWorkingDuration,

minimizeDistance

string

The time zone is a string code which identifies a region of the world in the "time zone database", also called "tz database". The tz database is a partition of the world into regions where local clocks all show the same time. This database gives the rules for time offset and daylight saving time in each region.

How do we use it?

In order to work with time events accurately, we usually use datetimes in the iso-8601 format, without explicit time zone. This format is quite well suported by many programming languages, and it is well suited for technical data exchange. But it is not easy to use for humans.

For instance, here are three datetimes in iso-8601 format, which give the same exact moment in time:

"2025-05-22T05:43:00Z"
"2025-05-22T06:43:00+01:00"
"2025-05-22T07:43:00+02:00"

For a non-technical user, it is difficult to know how to relate this to the time displayed on a watch or a clock.

We improve the user experience by adding the support of local datetimes, thanks to the use of the time zone, which allows to transform a local datetime into an iso-8601 datetime:

local datetime + timezone (tz) = iso-8601 datetime

For instance, here are five datetimes which all give the same exact moment in time:

"2025-05-22T05:43:00Z"
"2025-05-22T06:43:00+01:00"
"2025-05-22T07:43:00+02:00"
"2025-05-22 07:43:00" + timezone "tz": "Europe/Paris"
"2025-05-22 07:43" + timezone "tz": "Europe/Paris"

Note: the last example ("2025-05-22 07:43") illustrates the support of local datetimes without seconds, which can be very practical for users.

In order for local datetimes to be supported, some JSON input objects contain a "tz" time zone property. This "tz" property is used to pre-process the JSON input payload, like this:

We check if a valid timezone can be extracted from the "tz" property,
If so, we perform the following actions:
- Walk through the whole JSON content to look for local datetimes,
- Use the timezone to transform each local datetime into an iso-8601 datetime.

Important: some objects contain a "properties" sub-object, which is a map of custom client data; the content of the "properties" sub-objects is always excluded from the time zone pre-processing.

Example:

"Europe/Paris"

lateDeparture

boolean

default:false

True if lateDeparture is requested for Resources, false otherwise.

Response

The simple plan was created.

[TO_VALIDATE] Description pending review by a Kardinal engineer.

item

object

A simple plan is a simplified representation of a plan, with simplified resources, simplified stops, and a simplified objective.

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

Authorizations

Path Parameters

Body

Response