osrmroute
DocsQuickstart
API documentation

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.

3D Load Planning prices
ModuleCredits per operation
Standard load planPOST /api/v1/load-plans30 credits
Manual placement revisionPOST /api/v1/load-plans/{id}/placement-revisions5 credits
Pallet planningPOST /api/v1/load-plans/palletize30 credits
Equipment comparisonPOST /api/v1/load-plans/compare40 credits
Multi-stop load planPOST /api/v1/load-plans/multi-stop50 credits
Large cargo manifest129–256 cargo units per planPOST /api/v1/load-plans/bulk50 credits
Multi-vehicle allocationPOST /api/v1/load-plans/fleet70 credits
Vehicle and route comparisonPOST /api/v1/load-plans/dispatch100 credits
Pallet-to-truck loadingPOST /api/v1/load-plans/fulfillment60 credits
Historical shipment simulationPOST /api/v1/load-plans/simulation200 credits
Carton planningPOST /api/v1/load-plans/packaging30 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.

GET /api/v1/load-plans/prices
curl --fail -H "Authorization: Bearer $OSRM_API_KEY" https://osrmroute.com/api/v1/load-plans/prices

Submit a synthetic job

  1. Create a live API key linked to your project with route access. Send it as a Bearer token from your server.
  2. Use consistent units across the JSON manifest. Declare the equipment opening, interior dimensions and payload, then add cargo sizes, weights, quantities, orientations and stops.
  3. 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.
POST /api/v1/load-plans
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
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
}
mixed-stack.json
{
  "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.

GET /api/v1/load-plans/{id}
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}/cancel
  • DELETE /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}/worksheet
  • GET /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/prices
  • POST /api/v1/load-plans/import-preview
  • POST /api/v1/load-plans/compare
  • POST /api/v1/load-plans/fleet
  • POST /api/v1/load-plans/palletize
  • POST /api/v1/load-plans/multi-stop
  • POST /api/v1/load-plans/bulk
  • POST /api/v1/load-plans/packaging
  • POST /api/v1/load-plans/dispatch · Vehicle and route comparison
  • POST /api/v1/load-plans/fulfillment · Pallet-to-truck loading
  • GET, POST /api/v1/load-plans/{id}/warehouse · Warehouse execution
  • POST /api/v1/load-plans/simulation · Historical shipment simulation
  • GET /api/v1/load-plans/{id}/simulation-report · CSV
  • GET /api/v1/load-plans/partner · Partner project
  • POST /api/v1/load-plans/{id}/axle-estimate
  • GET /api/v1/load-plans/webhook/events
  • POST /api/v1/load-plans/{id}/placement-preview
  • POST /api/v1/load-plans/{id}/placement-revisions
  • GET /api/v1/load-plans/{id}/pdf
  • GET /api/v1/load-plans/{id}/xlsx
  • POST /api/v1/load-plans/{id}/share
  • GET /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.

POST /api/v1/load-plans/packaging
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
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.

POST /api/v1/load-plans/dispatch
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
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.

POST /api/v1/load-plans/fulfillment
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
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

POST /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.

POST /api/v1/load-plans/simulation
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
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.

GET /api/v1/load-plans/partner
curl --fail -H "Authorization: Bearer $OSRM_API_KEY" https://osrmroute.com/api/v1/load-plans/partner
POST /api/v1/load-plans/{id}/share
{
  "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.

GET /api/v1/load-plans/{id}/model
curl --fail -H "Authorization: Bearer $OSRM_API_KEY" \
  "https://osrmroute.com/api/v1/load-plans/$JOB_ID/model" -o load-plan.glb

The /internal URL below represents an authenticated route in your application. Keep your OSRMRoute API key on your server.

Three.js · GLTFLoader
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);
POST /api/v1/load-plans/{id}/share
{
  "expiresInSeconds": 900,
  "embedOrigin": "https://warehouse.example.com"
}
iframe
<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>

OSRMRoute Support

Talk directly to our team

HERE TO HELP

How can we help?

Send a message. Ticket replies are also sent to your verified email.

Your chats

Your chats will appear here.