Integrate route optimization into an existing application with an SDK
Use this path when you add Kardinal to an application that already exists. You use the Python SDK or the TypeScript SDK. The steps are in four stages.Stage 1: before you write code
- Read the checklist Start here if you’re an AI agent. Start with the “At a glance” table. Then read rule 1, rule 2, rule 3, rule 5, rule 6, and rule 9.
- Use the Requirements briefing checklist. Ask the user every question at once. Include the question about where the sandbox and production keys are. Then wait for the answers before you write the code that builds the plan. In the meantime, you can write the rest, such as reading the key, submitting the plan, and the screens. Don’t turn on an option such as
lateDepartureorwithTraffic, and don’t addbreaks, unless the data or the user asks for it. If the user can’t answer now, leave each unanswered option unset, and make it a setting the operator can fill in. The operator is the company whose tours your app plans. Then list these settings for the user. The working time window (workingTimeWindow) is required, so it can’t stay unset. Read it from the operator’s data, such as each driver’s shift, or from a setting the operator fills in. Never write it as a constant in your code. If nobody can answer during your session, give that setting a starting value so the app can plan. Keep it in the settings, not in the code, and list it for the user as your assumption. - Find the closest case study, for example Cold-chain last-mile. Use it as a starting point. Don’t copy it as a model. Its settings, such as
withTraffic, its working hours and its breaks, belong to that example’s client. Keep one in your code only when the user confirms it. The SDK returns it as a typed plan:examples.cold_chain_plan()in Python, andexamples.coldChainPlan()in TypeScript.
Stage 2: write the plan
- Follow the Quickstart. Then read Loading an existing JSON payload and Validating locally before you spend credits. In Python, build the plan with
PlanCreate.model_validate_json. In TypeScript, build it withparsePlanCreate. Runkardinal initin your project. Thekardinalcommand needs an extra install. In Python, install"kardinal-ai[cli]". In TypeScript, also installcommander. See Installing the command-line tool. It writes a skill that tells your coding assistant how to use the SDK. - Read these sections only when the question comes up.
- Compartments set up before departure explains how to load a vehicle with several goods.
- Hard or preferred window explains which kind of time window to use.
- The default list explains which objectives apply when you write none.
- Dates and time zones explains how to write a time.
Stage 3: follow the optimization from a web backend
- Check the API key when your application starts. Call
whoami, then compare the agency it returns with the one in your configuration. A sandbox key and a production key look alike. Read Checking the key at startup. - Read Waiting in a web backend or serverless function. Submit the plan, then store its id. Read the state later. Never call
waitinside an HTTP request. - Keep the warnings that
submit,update, andreplacereturn, for example next to the plan id. A latergetdoesn’t return them. Show them in your application to the person who submitted the plan, for example the planner. The API returns a warning when it changes part of your plan, for example when you ask for a longermaxOptimizationDurationthan your limit allows. The sandbox also returns warnings that production doesn’t, for example when it forces straight-line (crow-fly) distances. These warnings aren’t errors. Build the message for the planner fromproperties.pathand the value stored at that path, not frommessageordetails. The SDKs also write each kind of warning in your logs. Read Warnings on successful calls. - Keep the id of the plan you submit for each day. When the planner runs that day again, for example with other settings, call
replaceon that id. Don’t callsubmitagain. A new plan bills every stop again. The same plan, with the same stops, isn’t billed again within 24 hours of its creation. Read Replacing a plan from your own data and How credits work.
Stage 4: test, then go to production
- Read Differences between sandbox and production. The sandbox limits the optimization time. Wait about one minute at most, as rule 9 says.
- Read Sizing
maxOptimizationDurationfor a large problem before you run a large plan. - Read How credits work. Tell the user before you run a plan in production.

