POST/v1/calculate

Full Request Example

A complete request body with every available field populated. Use this as a reference when building your integration. Fields marked optional can be omitted — remove // comments before sending.

Note:Fields marked // optional in the example can be omitted — their defaults apply automatically. Comments (//) are not valid JSON; strip them from your actual request body.

Structure overview

orderRoot object — name, number, and sections array
order.sections[]One entry per origin → destination leg
section.originOrigin location, handling capacity, and fees[]
section.destinationDestination location, handling capacity, and fees[]
section.transportTruck specs, movement rates, fuel, handling times, and detention
section.order_items[]Line items with quantity and UOM
route_profilesArray of HERE route profiles to calculate (min 1)
settingsDistance unit, final-return flag, and cost adjustments

POST /v1/calculate — full request body

{
"order": {
"name": "Aggregate Delivery — London",   // optional
"number": "ORD-2026-00142",              // optional
"hazardous_goods": null,                 // optional  enum: explosive | gas | flammable | combustible | oxidizer | poison | radioactive | corrosive | other
"tunnel_category": null,                 // optional  enum: B | C | D | E
"toll_transponder": null,                // optional  enum: prepay | cash | none
"sections": [
{
// ── Origin (plant) ──────────────────────────────────────────
"origin": {
"type": "plant",                   // required  enum: plant | customer | depot
"lat": 51.5074,                    // required
"lng": -0.1278,                    // required
// Plant-level handling capacity  (rate UOM: t | m3 | cu_yd per hour)
"loading_rate_value": 150,         // optional — capacity value (e.g. 150 t/h)
"loading_rate_uom": "t",           // optional  enum: t | m3 | cu_yd
"loading_cost_value": 45.00,       // optional — cost per hour (or flat)
"loading_cost_calc_method": "per_h",  // optional  enum: per_h | per_t | per_m3 | flat | included
"in_facility_time_minutes": 20,    // optional — gate / admin time at plant
// Named fees from the fee glossary (master data)
"fees": [                          // optional
{
"fee_name": "gate_fee",        // required — must match a glossary fee name
"calc_method": "flat_per_trip",// optional  enum: per_t | per_m3 | per_cu_yd | per_km | per_mi | flat_per_trip | flat_per_section | flat_per_order | none
"value": 12.50                 // optional — overrides the glossary default
},
{
"fee_name": "scale_ticket_fee",// required
"calc_method": "flat_per_trip",// optional  enum: per_t | per_m3 | per_cu_yd | per_km | per_mi | flat_per_trip | flat_per_section | flat_per_order | none
"value": 4.00                  // optional — overrides the glossary default
}
]
},
// ── Destination (non-facility drop point) ───────────────────
"destination": {
"type": null,                      // optional — enum: plant | null (null = non-facility location)
"lat": 51.4500,                    // required
"lng": -0.3800,                    // required
// Plant-level handling capacity at destination  (rate UOM: t | m3 | cu_yd per hour)
"unloading_rate_value": 120,          // optional — capacity value (e.g. 120 t/h)
"unloading_rate_uom": "t",            // optional  enum: t | m3 | cu_yd
"unloading_cost_value": 38.00,        // optional — cost per hour (or flat)
"unloading_cost_calc_method": "per_h",// optional  enum: per_h | per_t | per_m3 | flat | included
"in_facility_time_minutes": 15,       // optional
// Named fees from the fee glossary — calc_method and value override glossary defaults
"fees": [                             // optional
{
"fee_name": "release_fee",        // required — must match a glossary fee name
"calc_method": "flat_per_trip",   // optional  enum: per_t | per_m3 | per_cu_yd | per_km | per_mi | flat_per_trip | flat_per_section | flat_per_order | none
"value": 8.00                     // optional — overrides glossary default
},
{
"fee_name": "document_fee",       // required
"calc_method": "flat_per_trip",   // optional  enum: per_t | per_m3 | per_cu_yd | per_km | per_mi | flat_per_trip | flat_per_section | flat_per_order | none
"value": 6.50                     // optional — overrides glossary default
}
]
},
// ── Transport (truck) ────────────────────────────────────────
"transport": {
"name": "Volvo FH 6x4",              // optional — label only
"max_load_weight_value": 28,       // required — payload capacity in weight
"max_load_weight_uom": "t",        // required  enum: t
"max_load_volume_value": 60,       // required — payload capacity in volume
"max_load_volume_uom": "m3",       // required when max_load_volume_value is set  enum: m3 | cu_yd
// Dimensions — forwarded to HERE routing
"height_m": 4.0,                   // required
"length_m": 16.5,                  // required
"width_m": 2.55,                   // required
"truck_weight_t": 44,              // required — empty/unladen truck weight in tonnes
"weight_t": 72,                    // required — gross vehicle weight (truck + max payload) in tonnes
"axle_count": 5,                   // required
"trailer_count": 1,                // optional
// Fuel & emissions
"fuel_type": "diesel",             // required  enum: diesel | petrol | electric | hydrogen | lng | cng
"registration_country": "GB",      // optional  ISO-3166-1 alpha-2
// Movement cost method
"calc_method": "distance",           // required  enum: distance | time
"cost_per_distance_loaded": 2.85,  // required if calc_method = distance
"cost_per_distance_loaded_uom": "km", // required if calc_method = distance  enum: km | mi
"cost_per_distance_empty": 1.40,   // required if calc_method = distance
"cost_per_distance_empty_uom": "km",  // required if calc_method = distance  enum: km | mi
"cost_per_h_loaded": null,         // required if calc_method = time
"cost_per_h_empty": null,          // required if calc_method = time
// Fuel consumption (drives fuel cost calculation)
"fuel_consumption_loaded": 32,             // optional
"fuel_consumption_loaded_uom": "l_per_km", // optional  enum: l_per_km | l_per_mi
"fuel_consumption_empty": 24,              // optional
"fuel_consumption_empty_uom": "l_per_km",  // optional  enum: l_per_km | l_per_mi
"fuel_price_value": 1.65,                  // optional — override system price (always USD)
"fuel_price_uom": "per_liter",             // optional  enum: per_liter | per_gallon
// Handling times (transport-side capacity)
"min_full_loading_time_minutes": 15,      // optional — minimum regardless of quantity
"full_loading_time_minutes": 45,           // optional — full-load baseline
"min_full_unloading_time_minutes": 10,    // optional
"full_unloading_time_minutes": 30,         // optional
// Detention (transport-specific waiting cost)
"detention": {
"min_waiting_time_free_minutes": 30,    // optional — shared free time for loading & unloading
"loading_rate_value": 75.00,            // optional
"loading_rate_calc_method": "per_h",    // optional  enum: per_h | flat | none
"unloading_rate_value": 75.00,          // optional
"unloading_rate_calc_method": "per_h"   // optional
},
// Small load surcharge
"small_load_limit_value": 20,              // optional
"small_load_limit_type": "t",              // optional  enum: t | m3 | cu_yd | pct
"small_load_surcharge_value": 95.00        // optional
},
// ── Order items ──────────────────────────────────────────────
"order_items": [
{
"name": "Aggregate 10mm",           // optional — label
"quantity_value": 25,               // required
"quantity_uom": "t",                // required  enum: t | m3 | cu_yd
"loading_rate_per_h": 150,          // optional — UOM is {quantity_uom}/h (e.g. quantity_uom = "t" → t/h)
"unloading_rate_per_h": 120         // optional — UOM is {quantity_uom}/h (same as quantity_uom)
}
],
}
]
},
// ── Route profiles ─────────────────────────────────────────────────
"route_profiles": ["fast", "short", "no_tolls"],  // required — at least one
// ── Settings (optional — global calculation adjustments) ───────────
"settings": {
"system": "metric",                     // required  enum: metric | imperial
"between_loads_only": false,            // required — true: cost only the loaded leg, no empty return; false: include empty return in cost
"include_final_return": true,           // required — true: add an empty return trip after the last section; false: one-way only
"trip_time_adjustment_pct": 5,          // optional — % added to HERE drive time
"trip_distance_adjustment_pct": 0,      // optional — % added to HERE distance
"risk_adjustment_pct": 3,              // optional — % added to total cost
"complexity_factor_pct": 2             // optional — % added to total cost
}
}