Load Planning API and 3D Integration Guide
Use the REST API to submit a cargo manifest, retrieve load placement and loading steps, and display the verified 3D model in your own application.
3D Load Planning prices
Each operation has one total price in purchased credits. A verified full plan or a permitted partial plan is chargeable under the operation’s rules. The reservation is returned when a job ends without a chargeable result.
| Module | Credits per operation |
|---|---|
Standard load planPOST /api/v1/load-plans | 30 credits |
Manual placement revisionPOST /api/v1/load-plans/{id}/placement-revisions | 5 credits |
Pallet planningPOST /api/v1/load-plans/palletize | 30 credits |
Equipment comparisonPOST /api/v1/load-plans/compare | 40 credits |
Multi-stop load planPOST /api/v1/load-plans/multi-stop | 50 credits |
Large cargo manifest129–256 cargo units per planPOST /api/v1/load-plans/bulk | 50 credits |
Multi-vehicle allocationPOST /api/v1/load-plans/fleet | 70 credits |
Vehicle and route comparisonPOST /api/v1/load-plans/dispatch | 100 credits |
Pallet-to-truck loadingPOST /api/v1/load-plans/fulfillment | 60 credits |
Historical shipment simulationPOST /api/v1/load-plans/simulation | 200 credits |
Carton planningPOST /api/v1/load-plans/packaging | 30 credits |
Checking a placement preview and exporting a verified result add no credit charge. Saving a verified placement revision has its own price.
Use the live price response before submitting a job. For a separately priced module, send its current credit price in Confirm-Load-Credits. A null price means the operation is unavailable.
curl --fail -H "Authorization: Bearer $OSRM_API_KEY" https://osrmroute.com/api/v1/load-plans/pricesSubmit a synthetic job
- Create a live API key linked to your project with route access. Send it as a Bearer token from your server.
- Use consistent units across the JSON manifest. Declare the equipment opening, interior dimensions and payload, then add cargo sizes, weights, quantities, orientations and stops.
- Set an Idempotency-Key before submitting. Save the job ID from the 202 response. If the response is lost, retry the same request with the same key. Follow Retry-After when polling.
curl -i -X POST "https://osrmroute.com/api/v1/load-plans" \
-H "Authorization: Bearer $OSRM_API_KEY" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: synthetic-truck-01' \
--data-binary @truck.json{
"units": {
"length": "mm",
"mass": "kg"
},
"equipment": {
"id": "synthetic-truck",
"kind": "truck",
"source": "template",
"inside": [
6000,
2400,
2400
],
"outside": [
7200,
2500,
3600
],
"door": {
"left": 25,
"width": 2350,
"height": 2300
},
"payload": 8000,
"tare": 6500,
"clearance": 25,
"obstacles": []
},
"stops": [
"s1",
"s2"
],
"items": [
{
"id": "p1",
"size": [
1200,
800,
1100
],
"mass": 350,
"quantity": 1,
"stopId": "s1",
"orientations": [
"lwh",
"wlh"
],
"stacking": "floor_only"
},
{
"id": "p2",
"size": [
1200,
800,
1100
],
"mass": 350,
"quantity": 1,
"stopId": "s2",
"orientations": [
"lwh",
"wlh"
],
"stacking": "floor_only"
}
],
"allowPartial": false
}{
"units": {
"length": "mm",
"mass": "kg"
},
"equipment": {
"id": "synthetic-compact-truck",
"kind": "truck",
"source": "template",
"inside": [
2400,
1000,
1500
],
"outside": [
3000,
1200,
1800
],
"door": {
"left": 0,
"width": 1000,
"height": 1500
},
"payload": 1000,
"tare": 600,
"clearance": 0,
"obstacles": []
},
"stops": [
"first",
"second"
],
"items": [
{
"id": "small",
"size": [
800,
650,
400
],
"mass": 70,
"quantity": 2,
"stopId": "first",
"orientations": [
"lwh"
],
"stacking": "stackable"
},
{
"id": "medium",
"size": [
1050,
850,
450
],
"mass": 90,
"quantity": 2,
"stopId": "first",
"orientations": [
"lwh"
],
"stacking": "stackable",
"maxTopMass": 100
},
{
"id": "base",
"size": [
1200,
1000,
600
],
"mass": 160,
"quantity": 2,
"stopId": "second",
"orientations": [
"lwh"
],
"stacking": "floor_only",
"maxTopMass": 180
}
],
"allowPartial": false
}Read the result
A completed job can contain a verified fit, a proof of infeasibility, no plan found, or a search limit. A partial fit requires explicit consent.
Check result.status and billing.status separately. A completed job can return no usable placement. When a partial fit is allowed, review the unplaced units before dispatch.
Poll GET with the returned job ID. Cancel requests cancellation of queued or running work. DELETE removes the retained input and result of a terminal job.
curl --include -H "Authorization: Bearer $OSRM_API_KEY" \
"https://osrmroute.com/api/v1/load-plans/$JOB_ID"GET /api/v1/load-plans/{id}POST /api/v1/load-plans/{id}/cancelDELETE /api/v1/load-plans/{id}
A verified plan and export permission are required. The worksheet downloads as HTML, the table as CSV and the 3D model as GLB.
GET /api/v1/load-plans/{id}/worksheetGET /api/v1/load-plans/{id}/csv
To revise a terminal job, submit the updated manifest with Revises-Load-Plan and a new idempotency key. Export is available for the latest verified revision.
The calculation uses the supplied dimensions and constraints. Before handling cargo, confirm equipment measurements, clearance, restraint, axle limits and applicable rules with the operator.
Equipment comparison, fleet and pallets
The company server uses its project key, reads the current price and queues the confirmed request.
GET /api/v1/load-plans/pricesPOST /api/v1/load-plans/import-previewPOST /api/v1/load-plans/comparePOST /api/v1/load-plans/fleetPOST /api/v1/load-plans/palletizePOST /api/v1/load-plans/multi-stopPOST /api/v1/load-plans/bulkPOST /api/v1/load-plans/packagingPOST /api/v1/load-plans/dispatch· Vehicle and route comparisonPOST /api/v1/load-plans/fulfillment· Pallet-to-truck loadingGET, POST /api/v1/load-plans/{id}/warehouse· Warehouse executionPOST /api/v1/load-plans/simulation· Historical shipment simulationGET /api/v1/load-plans/{id}/simulation-report· CSVGET /api/v1/load-plans/partner· Partner projectPOST /api/v1/load-plans/{id}/axle-estimateGET /api/v1/load-plans/webhook/eventsPOST /api/v1/load-plans/{id}/placement-previewPOST /api/v1/load-plans/{id}/placement-revisionsGET /api/v1/load-plans/{id}/pdfGET /api/v1/load-plans/{id}/xlsxPOST /api/v1/load-plans/{id}/shareGET /api/v1/load-plans/workspace/{kind}
Carton planning
Send the dimensions and weights of the items in an order. Choose a fitting carton from your catalog, suggest dimensions for a new carton, or calculate repeated-item capacity.
Use the live price response before submitting a job. For a separately priced module, send its current credit price in Confirm-Load-Credits. A null price means the operation is unavailable.
curl --fail-with-body -X POST "https://osrmroute.com/api/v1/load-plans/packaging" \
-H "Authorization: Bearer $OSRM_API_KEY" \
-H 'Content-Type: application/json' \
-H "Idempotency-Key: $IDEMPOTENCY_KEY" \
-H "Confirm-Load-Credits: $CONFIRMED_CREDITS" \
--data-binary @packaging.json{
"operation": "choose_carton",
"units": {
"length": "mm",
"mass": "g"
},
"stops": [
"order"
],
"items": [
{
"id": "sku",
"size": [
50,
50,
50
],
"mass": 100,
"quantity": 2,
"stopId": "order",
"orientations": [
"lwh"
],
"stacking": "floor_only"
}
],
"cartons": [
{
"id": "standard",
"inside": [
110,
110,
110
],
"payload": 1000,
"tare": 10
}
]
}Vehicle and route comparison
Compare single-truck and fleet options for the same shipment. Review fit, distance, duration, cost based on your rates, and vehicle count. Route results depend on Truck Routing coverage.
Use the live price response before submitting a job. For a separately priced module, send its current credit price in Confirm-Load-Credits. A null price means the operation is unavailable.
curl --fail-with-body -X POST "https://osrmroute.com/api/v1/load-plans/dispatch" \
-H "Authorization: Bearer $OSRM_API_KEY" \
-H 'Content-Type: application/json' \
-H "Idempotency-Key: $IDEMPOTENCY_KEY" \
-H "Confirm-Load-Credits: $CONFIRMED_CREDITS" \
--data-binary @dispatch.json{
"manifest": {
"units": {
"length": "mm",
"mass": "kg"
},
"stops": [
"s1"
],
"items": [
{
"id": "p1",
"size": [
1200,
800,
1100
],
"mass": 350,
"quantity": 1,
"stopId": "s1",
"orientations": [
"lwh",
"wlh"
],
"stacking": "floor_only"
}
],
"allowPartial": false
},
"currency": "USD",
"points": [
[
49.865,
40.405
],
[
49.902,
40.421
]
],
"alternatives": [
{
"id": "standard",
"vehicles": [
{
"equipment": {
"id": "synthetic-truck",
"kind": "truck",
"source": "template",
"inside": [
6000,
2400,
2400
],
"outside": [
7200,
2500,
3600
],
"door": {
"left": 25,
"width": 2350,
"height": 2300
},
"payload": 8000,
"tare": 6500,
"clearance": 25,
"obstacles": []
},
"vehicle": {
"height_m": 3.6,
"width_m": 2.5,
"length_m": 7.2,
"weight_t": 14.5,
"axle_load_t": 8,
"axle_count": 2
},
"baseMinor": 850,
"perKilometerMinor": 160
}
]
}
]
}Pallet-to-truck loading
Pack items onto pallets and load the pallets into a truck. See each pallet’s contents, the 3D scene, and loading order. Operators can scan barcodes and record exceptions against a specific revision.
Use the live price response before submitting a job. For a separately priced module, send its current credit price in Confirm-Load-Credits. A null price means the operation is unavailable.
curl --fail-with-body -X POST "https://osrmroute.com/api/v1/load-plans/fulfillment" \
-H "Authorization: Bearer $OSRM_API_KEY" \
-H 'Content-Type: application/json' \
-H "Idempotency-Key: $IDEMPOTENCY_KEY" \
-H "Confirm-Load-Credits: $CONFIRMED_CREDITS" \
--data-binary @fulfillment.json{
"pallet": {
"pallet": {
"lengthMm": 1200,
"widthMm": 800,
"deckHeightMm": 145,
"maxTotalHeightMm": 1250,
"tareG": 20000,
"maxCargoMassG": 1000000,
"maxPallets": 2,
"maxLayers": 3
},
"stopId": "s1",
"items": [
{
"id": "carton",
"size": [
400,
400,
300
],
"mass": 10000,
"quantity": 5,
"stopId": "s1",
"orientations": [
"lwh"
],
"stacking": "stackable",
"maxTopMass": 30000
}
],
"allowPartial": false
},
"truckEquipment": {
"id": "synthetic-truck",
"kind": "truck",
"source": "template",
"inside": [
6000,
2400,
2400
],
"outside": [
7200,
2500,
3600
],
"door": {
"left": 25,
"width": 2350,
"height": 2300
},
"payload": 8000000,
"tare": 6500000,
"clearance": 25,
"obstacles": []
}
}GET /api/v1/load-plans/{id}/warehouse
{
"revision": 1,
"eventId": "scan-0001",
"unitId": "pallet-1:1"
}Historical shipment simulation
Replay past shipments with the same cargo across two scenarios. Get vehicle count, utilization, unplaced units, and the difference between known costs in JSON and CSV.
Use the live price response before submitting a job. For a separately priced module, send its current credit price in Confirm-Load-Credits. A null price means the operation is unavailable.
curl --fail-with-body -X POST "https://osrmroute.com/api/v1/load-plans/simulation" \
-H "Authorization: Bearer $OSRM_API_KEY" \
-H 'Content-Type: application/json' \
-H "Idempotency-Key: $IDEMPOTENCY_KEY" \
-H "Confirm-Load-Credits: $CONFIRMED_CREDITS" \
--data-binary @simulation.json{
"currency": "USD",
"shipments": [
{
"id": "demo-shipment",
"manifest": {
"units": {
"length": "mm",
"mass": "kg"
},
"stops": [
"s1"
],
"items": [
{
"id": "p1",
"size": [
1200,
800,
1100
],
"mass": 350,
"quantity": 1,
"stopId": "s1",
"orientations": [
"lwh",
"wlh"
],
"stacking": "floor_only"
}
],
"allowPartial": false
},
"baseline": {
"version": "2026-a",
"alternatives": [
{
"id": "synthetic-truck",
"kind": "truck",
"source": "template",
"inside": [
6000,
2400,
2400
],
"outside": [
7200,
2500,
3600
],
"door": {
"left": 25,
"width": 2350,
"height": 2300
},
"payload": 8000,
"tare": 6500,
"clearance": 25,
"obstacles": []
}
],
"vehicleCostMinor": {
"synthetic-truck": 1500
}
},
"proposed": {
"version": "2026-b",
"alternatives": [
{
"id": "synthetic-truck",
"kind": "truck",
"source": "template",
"inside": [
6000,
2400,
2400
],
"outside": [
7200,
2500,
3600
],
"door": {
"left": 25,
"width": 2350,
"height": 2300
},
"payload": 8000,
"tare": 6500,
"clearance": 25,
"obstacles": []
}
],
"vehicleCostMinor": {
"synthetic-truck": 1250
}
}
}
]
}GET /api/v1/load-plans/{id}/simulation-report · CSV
Partner project
Keep a separate project and API key for each customer. The account owner sets the monthly credit cap, the approved HTTPS origin, and the brand shown in the 3D viewer.
curl --fail -H "Authorization: Bearer $OSRM_API_KEY" https://osrmroute.com/api/v1/load-plans/partner{
"expiresInSeconds": 900,
"partnerEmbed": true
}Display the 3D model in your application
The verified scene includes the cargo space, loading opening, obstacles and the coordinates and oriented dimensions of placed units in millimetres.
Review loading and unloading steps in 3D. Show a verified plan in a TMS, WMS, or customer portal through an expiring iframe, or open the GLB in your own viewer.
Download the latest verified plan as a GLB from your server. This export adds no credit charge.
curl --fail -H "Authorization: Bearer $OSRM_API_KEY" \
"https://osrmroute.com/api/v1/load-plans/$JOB_ID/model" -o load-plan.glbThe /internal URL below represents an authenticated route in your application. Keep your OSRMRoute API key on your server.
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
const path = '/internal/load-plans/' + encodeURIComponent(jobId) + '/model';
const response = await fetch(path, { credentials: 'same-origin' });
if (!response.ok) throw new Error('Load model unavailable');
const { scene: loadModel } = await new GLTFLoader().parseAsync(await response.arrayBuffer(), '');
viewerScene.add(loadModel);{
"expiresInSeconds": 900,
"embedOrigin": "https://warehouse.example.com"
}<iframe title="3D load plan" src="https://osrmroute.com{path}"
width="100%" height="640" loading="lazy" referrerpolicy="no-referrer"
sandbox="allow-scripts allow-same-origin"></iframe>