API Documentation

Base URL & Authentication

All requests must be made over HTTPS. Your API key is available in your account dashboard after subscription.

Endpoints Overview

POST /calculate

Calculate CBM and freight metrics for one or more items. This is the primary endpoint.

Request Body

{
  "items": [
    {
      "description": "string (optional)",
      "length": number,           // required
      "width":  number,           // required
      "height": number,           // required
      "unit": "cm|mm|m|in|ft",   // default: "cm"
      "quantity": integer,        // default: 1
      "weight_kg": number         // optional — enables chargeable weight calc
    }
  ]
}

Response

{
  "success": true,
  "items": [
    {
      "description": "string",
      "length_m": 0.6,
      "width_m": 0.4,
      "height_m": 0.5,
      "cbm_unit": 0.12,
      "total_cbm": 2.4,
      "total_cft": 84.74,
      "total_litres": 2400,
      "quantity": 20,
      "weight_kg_unit": 15,
      "total_weight_kg": 300
    }
  ],
  "totals": {
    "cbm": 5.28,
    "cft": 186.44,
    "litres": 5280,
    "weight_kg": 550,
    "vol_weight_sea_kg": 5280,
    "vol_weight_air_kg": 31680,
    "chargeable_sea": "cbm",     // "cbm" or "weight"
    "chargeable_air": "volume",  // "volume" or "weight"
    "fit_20gp": 6,
    "fit_40gp": 12,
    "fit_40hc": 14
  }
}

POST /volumetric-weight

Calculate chargeable weight for air freight, sea LCL, and courier shipments.

Request Body

{
  "length": number,
  "width":  number,
  "height": number,
  "unit": "cm|mm|m|in|ft",
  "quantity": integer,
  "actual_weight_kg": number,
  "mode": "air|sea|courier"     // default: "air"
}

Response

{
  "success": true,
  "cbm": 2.4,
  "actual_weight_kg": 180,
  "volumetric_weight_kg": 14400,
  "chargeable_weight_kg": 14400,
  "chargeable_basis": "volumetric",
  "mode": "air",
  "divisor": 6000
}

POST /convert

Convert between units of length, weight or volume.

Request Body

{
  "value": 100,
  "from": "cm",
  "to": "in",
  "type": "length|weight|volume"
}

GET /status

Check API status and remaining monthly call quota.

GET /status
Authorization: Bearer YOUR_API_KEY

// Response:
{
  "status": "ok",
  "plan": "standard",
  "calls_used": 1247,
  "calls_limit": 5000,
  "reset_date": "2026-05-01",
  "api_version": "1.0"
}

Error Codes

Error Response Format

{
  "success": false,
  "error": "INVALID_PARAMS",
  "message": "The 'length' field is required and must be a positive number."
}

Code Examples

PHP

$apiKey = 'YOUR_API_KEY';
$data = [
    'items' => [
        ['length'=>60,'width'=>40,'height'=>50,'unit'=>'cm','quantity'=>20,'weight_kg'=>15]
    ]
];
$ch = curl_init('https://api.calculatecbm.com/v1/calculate');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer '.$apiKey,
    'Content-Type: application/json'
]);
$response = json_decode(curl_exec($ch), true);
echo $response['totals']['cbm']; // 2.4

Python

import requests

headers = {'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json'}
data = {
    'items': [
        {'length': 60, 'width': 40, 'height': 50, 'unit': 'cm', 'quantity': 20, 'weight_kg': 15}
    ]
}
r = requests.post('https://api.calculatecbm.com/v1/calculate', json=data, headers=headers)
print(r.json()['totals']['cbm'])  # 2.4

JavaScript (Node.js)

const res = await fetch('https://api.calculatecbm.com/v1/calculate', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    items: [{ length: 60, width: 40, height: 50, unit: 'cm', quantity: 20, weight_kg: 15 }]
  })
});
const data = await res.json();
console.log(data.totals.cbm); // 2.4