Skip to main content
This page takes you from an empty project to an optimized route with the SDK of your choice. It uses the example plan shipped with both SDKs: two vehicles and eight deliveries around central Paris.

Before you start

You need:
  • An API key. Sign up on the Console and generate a key for your sandbox agency — see Authentication and API keys. A sandbox key consumes no credits, which makes it the right key for this page.
  • A runtime. Python 3.10 or later, or Node.js 22 or later.

Installing the package

Install the Python package in a virtual environment, which is a private folder of packages for one project. Installation explains why.
The Python package installs as kardinal-ai and imports as kardinal. See Installation for the kardinal command-line tool and the module formats.

Setting your API key

Both SDKs read the key from the KARDINAL_API_KEY environment variable:
Keep the key out of your source code. Client configuration covers the other ways to pass it.

Submitting the example plan

submit sends the plan, which starts its optimization, and returns it with the id the server assigned. wait follows the optimization and returns the solution once it’s over. The example plan asks for a 10-second optimization. The sandbox caps optimizations at 5 seconds, so submit returns a warning saying the duration was clamped: that’s expected, and plan.warnings lists it.

Reading the result

Each tour is the route of one resource. It lists its waypoints in order: the beginning, then the stops with any breaks between them, then the end. The snippet keeps only the stops. arrivalTime is when the vehicle gets to a stop. beginTime is when the service starts. When the vehicle arrives before the stop’s time window opens, it waits, so beginTime is later than arrivalTime. Show beginTime to your customer. A stop the engine could not plan is in no tour. It is listed in unaffectedStopIds, and no error reports it. The final state says how the optimization ended: check it before treating the result as final. See Retrieve a plan solution in the API Reference for every field of the solution.

Why wait rather than get

The API is asynchronous. Right after submit, the plan is still waiting or being processed: solutions.get then fails with a 404, and a moment later returns whatever the engine has found so far, which can be empty or incomplete. wait returns only once the optimization is over.

Next steps