Create a plan

Error

A valid request URL is required to generate request examples

{
  "item": {
    "resources": [
      {
        "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": [
          {
            "policy": "withoutFirstOperationDuration",
            "stopTags": [
              "access:parking33",
              "capa:bat22",
              "setup:france"
            ]
          }
        ],
        "travelTimeCoefficient": 1.05,
        "emptyThresholdByCapacity": {
          "volume": 50,
          "weight": 100,
          "nbPackages": 23
        },
        "avoidEarlyLoadings": [
          {
            "stopTag": "depot1",
            "capacities": [
              "weight",
              "volume"
            ]
          }
        ]
      }
    ],
    "id": "4cbd0ab8-282c-4b30-b981-29e1ed8a2016",
    "agencyId": "BLD1234567_production",
    "version": 42,
    "running": true,
    "status": {
      "planVersionInSolution": 42,
      "waitingRoom": {
        "waitingVersion": 42,
        "runningVersion": 42
      },
      "waitingTraffic": {
        "waitingVersion": 42,
        "runningVersion": 42
      },
      "creation": {
        "waitingVersion": 42,
        "runningVersion": 42
      },
      "optimization": {
        "waitingVersion": 42,
        "runningVersion": 42
      }
    },
    "state": "waiting",
    "properties": {},
    "nbResources": 1,
    "orders": [
      {
        "id": "<string>",
        "stops": [
          {
            "id": "<string>",
            "position": {
              "lon": 2.3269331,
              "lat": 48.8812658
            },
            "type": "single",
            "properties": {},
            "tags": [
              "access:parking33",
              "capa:bat22",
              "setup:france"
            ],
            "kind": "delivery",
            "operationDuration": "PT4M",
            "capacities": {
              "volume": 9.5,
              "weight": 2200,
              "nbPackages": 23
            },
            "authorizedTimeWindows": [
              {
                "begin": "2019-11-15T12:34:56Z",
                "end": "2019-11-15T12:34:56Z",
                "resourceTags": [
                  "subcontractorA",
                  "subcontractorB"
                ]
              }
            ],
            "preferredTimeWindows": [
              {
                "begin": "2019-11-15T12:34:56Z",
                "end": "2019-11-15T12:34:56Z",
                "resourceTags": [
                  "subcontractorA",
                  "subcontractorB"
                ]
              }
            ]
          }
        ],
        "properties": {},
        "priority": 0,
        "optional": true,
        "requiredSkills": [
          "forklift",
          "truck"
        ],
        "successiveStops": true,
        "maxStopSpan": "PT4M"
      }
    ],
    "nbOrders": 1,
    "additionalOperationDurations": [
      {
        "resourceTag": "trailer",
        "stopTag": "heavy",
        "additionalOperationDuration": "PT4M"
      }
    ],
    "operationDurationPoliciesByResourceTag": {},
    "additionalConstraints": [
      {
        "type": "atLeastOneValidCapacity",
        "capacities": {
          "volume": 9.5,
          "weight": 2200,
          "nbPackages": 23
        },
        "name": "<string>",
        "resourceTags": [
          "subcontractorA",
          "subcontractorB"
        ]
      }
    ],
    "globalConstraints": [
      {
        "type": "maxCumulatedCost",
        "costsByResourceTag": {},
        "name": "<string>",
        "maximum": 123
      }
    ],
    "accessDurationsByStopTag": {
      "access:parking33": "PT5M"
    },
    "overlappingCapacitiesByStopTag": {
      "capa:bat22": 3
    },
    "setupDurations": [
      {
        "fromStopTag": "setup:france",
        "toStopTag": "setup:belgium",
        "setupDuration": "PT4M"
      }
    ],
    "objectives": [
      "maximizeMandatoryStops",
      "minimizeDelay",
      "minimizeCosts",
      "minimizeResources",
      "minimizeOverOverlappingCapacitiesOnStops",
      "maximizeOptionalStops",
      "maximizePreferredStops",
      "minimizeWorkingDuration",
      "minimizeDistance"
    ],
    "maxOptimizationDuration": "PT4M",
    "tz": "Europe/Paris",
    "createdAt": "2019-11-15T12:34:56Z",
    "createdBy": "<string>",
    "updatedAt": "2019-11-15T12:34:56Z",
    "updatedBy": "<string>",
    "archivedAt": null,
    "lateDeparture": false,
    "sharedCapacities": false,
    "emptyThresholdByCapacityByResourceTag": {
      "heavy": {
        "weight": 150,
        "volume": 75
      },
      "*": {
        "weight": 50
      }
    },
    "avoidEarlyLoadingsByResourceTag": {
      "*": [
        {
          "stopTag": "depot1",
          "capacities": [
            "weight",
            "volume"
          ]
        }
      ],
      "heavy": [
        {
          "stopTag": "warehouse"
        }
      ]
    },
    "CO2EmissionCalculationByResourceTag": {
      "resTag2": {
        "km": {
          "costCoeff": 0.55
        },
        "costPerCapacityPerTravelledKm": {
          "weight": {
            "costCoeff": 0.2
          }
        }
      }
    }
  },
  "agencyId": "BLD1234567_production",
  "planId": "4cbd0ab8-282c-4b30-b981-29e1ed8a2016",
  "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": {}
    }
  ]
}

POST

plans

Error

A valid request URL is required to generate request examples

{
  "item": {
    "resources": [
      {
        "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": [
          {
            "policy": "withoutFirstOperationDuration",
            "stopTags": [
              "access:parking33",
              "capa:bat22",
              "setup:france"
            ]
          }
        ],
        "travelTimeCoefficient": 1.05,
        "emptyThresholdByCapacity": {
          "volume": 50,
          "weight": 100,
          "nbPackages": 23
        },
        "avoidEarlyLoadings": [
          {
            "stopTag": "depot1",
            "capacities": [
              "weight",
              "volume"
            ]
          }
        ]
      }
    ],
    "id": "4cbd0ab8-282c-4b30-b981-29e1ed8a2016",
    "agencyId": "BLD1234567_production",
    "version": 42,
    "running": true,
    "status": {
      "planVersionInSolution": 42,
      "waitingRoom": {
        "waitingVersion": 42,
        "runningVersion": 42
      },
      "waitingTraffic": {
        "waitingVersion": 42,
        "runningVersion": 42
      },
      "creation": {
        "waitingVersion": 42,
        "runningVersion": 42
      },
      "optimization": {
        "waitingVersion": 42,
        "runningVersion": 42
      }
    },
    "state": "waiting",
    "properties": {},
    "nbResources": 1,
    "orders": [
      {
        "id": "<string>",
        "stops": [
          {
            "id": "<string>",
            "position": {
              "lon": 2.3269331,
              "lat": 48.8812658
            },
            "type": "single",
            "properties": {},
            "tags": [
              "access:parking33",
              "capa:bat22",
              "setup:france"
            ],
            "kind": "delivery",
            "operationDuration": "PT4M",
            "capacities": {
              "volume": 9.5,
              "weight": 2200,
              "nbPackages": 23
            },
            "authorizedTimeWindows": [
              {
                "begin": "2019-11-15T12:34:56Z",
                "end": "2019-11-15T12:34:56Z",
                "resourceTags": [
                  "subcontractorA",
                  "subcontractorB"
                ]
              }
            ],
            "preferredTimeWindows": [
              {
                "begin": "2019-11-15T12:34:56Z",
                "end": "2019-11-15T12:34:56Z",
                "resourceTags": [
                  "subcontractorA",
                  "subcontractorB"
                ]
              }
            ]
          }
        ],
        "properties": {},
        "priority": 0,
        "optional": true,
        "requiredSkills": [
          "forklift",
          "truck"
        ],
        "successiveStops": true,
        "maxStopSpan": "PT4M"
      }
    ],
    "nbOrders": 1,
    "additionalOperationDurations": [
      {
        "resourceTag": "trailer",
        "stopTag": "heavy",
        "additionalOperationDuration": "PT4M"
      }
    ],
    "operationDurationPoliciesByResourceTag": {},
    "additionalConstraints": [
      {
        "type": "atLeastOneValidCapacity",
        "capacities": {
          "volume": 9.5,
          "weight": 2200,
          "nbPackages": 23
        },
        "name": "<string>",
        "resourceTags": [
          "subcontractorA",
          "subcontractorB"
        ]
      }
    ],
    "globalConstraints": [
      {
        "type": "maxCumulatedCost",
        "costsByResourceTag": {},
        "name": "<string>",
        "maximum": 123
      }
    ],
    "accessDurationsByStopTag": {
      "access:parking33": "PT5M"
    },
    "overlappingCapacitiesByStopTag": {
      "capa:bat22": 3
    },
    "setupDurations": [
      {
        "fromStopTag": "setup:france",
        "toStopTag": "setup:belgium",
        "setupDuration": "PT4M"
      }
    ],
    "objectives": [
      "maximizeMandatoryStops",
      "minimizeDelay",
      "minimizeCosts",
      "minimizeResources",
      "minimizeOverOverlappingCapacitiesOnStops",
      "maximizeOptionalStops",
      "maximizePreferredStops",
      "minimizeWorkingDuration",
      "minimizeDistance"
    ],
    "maxOptimizationDuration": "PT4M",
    "tz": "Europe/Paris",
    "createdAt": "2019-11-15T12:34:56Z",
    "createdBy": "<string>",
    "updatedAt": "2019-11-15T12:34:56Z",
    "updatedBy": "<string>",
    "archivedAt": null,
    "lateDeparture": false,
    "sharedCapacities": false,
    "emptyThresholdByCapacityByResourceTag": {
      "heavy": {
        "weight": 150,
        "volume": 75
      },
      "*": {
        "weight": 50
      }
    },
    "avoidEarlyLoadingsByResourceTag": {
      "*": [
        {
          "stopTag": "depot1",
          "capacities": [
            "weight",
            "volume"
          ]
        }
      ],
      "heavy": [
        {
          "stopTag": "warehouse"
        }
      ]
    },
    "CO2EmissionCalculationByResourceTag": {
      "resTag2": {
        "km": {
          "costCoeff": 0.55
        },
        "costPerCapacityPerTravelledKm": {
          "weight": {
            "costCoeff": 0.2
          }
        }
      }
    }
  },
  "agencyId": "BLD1234567_production",
  "planId": "4cbd0ab8-282c-4b30-b981-29e1ed8a2016",
  "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": {}
    }
  ]
}

Authorizations

Authorization

string

header

required

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

Body

application/json

The plan to create.

A full plan for a date and agency, with its associated resources, orders, constraints, ...

resources

object[]

required

Show child attributes

status

object

Show child attributes

state

enum<string>

The corresponding plan's state.

waiting: The plan was received and is awaiting processing.
processing: The plan is being processed.
preOptimizing: The plan is being optimized while awaiting traffic or other information.
preOptimized: While still awaiting traffic or other information, one of the following events has occurred: no better solution can be produced, or the optimization period has reached its limit. Note that 'preOptimized' should be followed by 'optimizing' and 'optimized'.
optimizing: The plan is being optimized with all required information.
optimized: This state can be triggered by one of the following events: no better solution can be produced, or the optimization period has reached its limit.
stopped: The plan's awaiting optimizations were canceled.
deleted: The plan was deleted and awaiting optimizations were canceled.
interrupted: The plan was either updated, stopped or deleted during its optimization.

Available options:

waiting,

processing,

preOptimizing,

preOptimized,

optimizing,

optimized,

stopped,

deleted,

interrupted

properties

object

Show child attributes

orders

object[]

Show child attributes

additionalOperationDurations

object[]

Additional operation time for a resource and a stop, according to tags (pairs of tags must be unique).

Show child attributes

operationDurationPoliciesByResourceTag

object

Policies to remove the operation durations, by resource tag.

Show child attributes

additionalConstraints

object[]

If the tour has not, at each stop, one of its capacities lower than or equal to the link limit, then the tour is invalid.

Show child attributes

globalConstraints

object[]

List of global constraints to be satisfied by the returned solution.

Show child attributes

accessDurationsByStopTag

object

Access durations is an additional duration before the beginning of a group of stops with the same stop tag.

Show child attributes

Example:

{ "access:parking33": "PT5M" }

overlappingCapacitiesByStopTag

object

This field allows users to define a limit in the number of resources that are simultaneously present at stops sharing the same stop tag.

Show child attributes

Example:

{ "capa:bat22": 3 }

setupDurations

object[]

Show child attributes

objectives

enum<string> · object · object[]

Available options:

maximizeMandatoryStops,

minimizeDelay,

minimizeCosts,

minimizeResources,

minimizeOverOverlappingCapacitiesOnStops,

maximizeOptionalStops,

maximizePreferredStops,

minimizeLargestTourDuration,

minimizeWorkingDuration,

minimizeDistance,

minimizeEarlyLoadings

maxOptimizationDuration

string

A period of time, expressed in the ISO8601 duration format.

Pattern: ^P(\d+Y)?(\d+M)?(\d+W)?(\d+D)?(T(\d+H)?(\d+M)?(\d+S)?)?$

Example:

"PT4M"

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.

sharedCapacities

boolean

default:false

True if sharedCapacities is requested for Resources, false otherwise. It enables resources to share capacities between stops of different orders.

emptyThresholdByCapacityByResourceTag

object

Thresholds for capacities below which a resource is considered "empty" for empty distance calculation, grouped by resource tag. A resource is "empty" (kilometers traveled count as empty distance) when all capacities are at or below their threshold. The wildcard tag "*" matches all resources.

Show child attributes

Example:

{
  "heavy": { "weight": 150, "volume": 75 },
  "*": { "weight": 50 }
}

avoidEarlyLoadingsByResourceTag

object

Early loading declarations grouped by resource tag. The wildcard tag "*" matches all resources. Each entry identifies a stop tag and optional capacities used to compute the minimizeEarlyLoadings objective.

Show child attributes

Example:

{
  "*": [
    {
      "stopTag": "depot1",
      "capacities": ["weight", "volume"]
    }
  ],
  "heavy": [{ "stopTag": "warehouse" }]
}

CO2EmissionCalculationByResourceTag

object

Optional CO2 emission calculation parameters grouped by resource tag. Each value is a Cost-shaped object. Applies to every resource carrying the corresponding tag. When set, the resulting emissions are reported on tours as CO2Emission and aggregated on the solution as CO2Emission. If a resource matches multiple tags, only its first declared matching tag is used. Overridden by the resource-level declaration.

Show child attributes

Example:

{
  "resTag2": {
    "km": { "costCoeff": 0.55 },
    "costPerCapacityPerTravelledKm": { "weight": { "costCoeff": 0.2 } }
  }
}

Response

Plan response created.

item

object

A full plan for a date and agency, with its associated resources, orders, constraints, ...

Show child attributes

agencyId

string

read-only

The agency id.

Pattern: ^BLD[0-9]{7}_[a-zA-Z0-9-._~:@!$,]+$

Example:

"BLD1234567_production"

planId

string<uuid>

read-only

The plan id.

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

Example:

"4cbd0ab8-282c-4b30-b981-29e1ed8a2016"

planVersion

integer

read-only

The plan version.

Required range: x >= 1

Example:

42

API

Data model

Changes

Authorizations

Body

Response