Freight Distance

Logistics Freight Distance API is useful to calculate and save emissions for a single freight trip using shipment, trip, distance, and vehicle details.

Request Parameters

Endpoint

/v3/logistics/freight-distance

Method

POST;

Headers

{
    "x-api-key": "API_KEY",
    "Content-Type": "application/json"
}

Payload

{
    "trip_id": "TRIP_1001",
    "customer_identifier": "CUST_001",
    "customer_industry": "Retail",
    "service_type": "FTL",
    "freight_segment": "Primary",
    "load_type": "Frozen",
    "teu": 0,
    "trip_timestamp": 1712090040000,
    "shipment_weight": {
        "weight_value": 2000,
        "weight_unit": "KGS"
    },
    "trip_weight": {
        "weight_value": 2400,
        "weight_unit": "KGS"
    },
    "address": {
        "origin_address": "Mumbai",
        "destination_address": "Delhi"
    },
    "distance": {
        "distance_travelled": 1400,
        "distance_unit": "Kms"
    },
    "vehicle": {
        "vehicle_identifier": "MH12AB1234",
        "vehicle_ownership": "Own",
        "vehicle_code": "HGV4",
        "vehicle_fueltype": "Diesel",
        "vehicle_make": "Tata",
        "vehicle_name": "Prima",
        "vehicle_engine_type": "Diesel",
        "vehicle_make_year": 2022
    },
    "shipment_sequence": 1,
    "is_trip_empty": false,
    "customer_items_count": 150,
    "total_items_count": 220,
    "empty_distance_included": false,
    "country": "INDIA"
}

Field Validation

Required fields

trip_id (string)
customer_industry (string)
service_type (string, enum)
trip_timestamp (number, min: 0)
shipment_weight.weight_value (number, min: 0)
shipment_weight.weight_unit (string, enum)
trip_weight.weight_value (number, min: 0)
trip_weight.weight_unit (string, enum)
address.origin_address (string)
address.destination_address (string)
distance.distance_travelled (number, min: 0)
distance.distance_unit (string, enum)
vehicle.vehicle_ownership (string)
vehicle.vehicle_code (string, enum)
vehicle.vehicle_fueltype (string, enum)
customer_items_count (number, min: 0)
total_items_count (number, min: 0)
country (string)

Optional fields

customer_identifier (string, empty string allowed)
freight_segment (string, empty string allowed)
load_type (string, empty string allowed)
teu (number, min: 0)
vehicle.vehicle_identifier (string, empty string allowed)
vehicle.vehicle_make (string, empty string allowed)
vehicle.vehicle_name (string, empty string allowed)
vehicle.vehicle_engine_type (string, empty string allowed)
vehicle.vehicle_make_year (number, min: 0)
shipment_sequence (number, min: 0)
is_trip_empty (boolean)
empty_distance_included (boolean)

Enum / limited values

service_type: ["FCL", "FTL", "LCL", ""]
shipment_weight.weight_unit: ["KGS"]
trip_weight.weight_unit: ["KGS"]
distance.distance_unit: ["Kms"]
vehicle.vehicle_code: ["SCD", "LCV1", "HGV2", "HGV4", "ACF", "LCV2", "LCV3", "ACB", "HGV", "TRAIN"]
vehicle.vehicle_fueltype: ["HFO", "Diesel", "Aviation Turbine Fuel", "", "Electric", "CNG"]

Notes

vehicle_code is also validated by business logic for transport mode mapping: Air, Sea, Road, Rail.
If request validation fails, API returns 400 with all validation messages joined in one response string.

Response Parameters

Status Code

200;

Response Data

The response returns persistence status and saved logistic request data.

{
  "success": true,
  "message": "Logistic data saved successfully",
  "data": {
    "id": 12456,
    "trip_id": "TRIP-001",
    "idempotency_key": "TRIP-001_1",
    "trip_timestamp": 1719206400,
    "trip_date": "2024-06-24T00:00:00.000Z",

    "service_type": "FTL",
    "freight_segment": "",
    "load_type": "",
    "teu": 0,

    "shipment_weight_value": 2000,
    "shipment_weight_unit": "KGS",
    "trip_weight_value": 2200,
    "trip_weight_unit": "KGS",

    "origin_address": "Mumbai",
    "destination_address": "Delhi",
    "distance_travelled_value": 1420.5,
    "distance_travelled_unit": "Kms",

    "vehicle_type": "Truck",
    "vehicle_identifier": "MH12AB1234",
    "vehicle_ownership": "Own",
    "vehicle_code": "HGV2",
    "vehicle_fueltype": "Diesel",
    "vehicle_make": "Tata",
    "vehicle_name": "Prima",
    "vehicle_engine_type": "BS6",
    "vehicle_make_year": 2022,

    "shipment_sequence": 1,
    "is_trip_empty": false,
    "customer_items_count": 10,
    "total_items_count": 10,
    "empty_distance_included": false,
    "country": "INDIA",

    "customer_id": 789,
    "client_id": "client_123",

    "total_emission_value": 345.12,
    "total_emission_unit": "kgCO2e",
    "total_activity_value": 2841000,
    "total_activity_unit": "kg.km",
    "well_to_tank_emission_value": 52.3,
    "well_to_tank_emission_unit": "kgCO2e",
    "tank_to_wheel_emission_value": 292.82,
    "tank_to_wheel_emission_unit": "kgCO2e",
    "emission_intensity_value": 0.1215,
    "emission_intensity_unit": "kgCO2e/kg.km",

    "payload_capacity": 0,
    "mode_of_transport": "Road",

    "createdAt": "2026-02-24T10:45:12.000Z",
    "updatedAt": "2026-02-24T10:45:12.000Z"
  }
}

caution

The error message is for your information, not for end users. Please use status codes and communicate user-friendly errors on your side. Validation failures can include multiple errors in a single response message.

Sample Request

cURL
NodeJs
Axios
Python
Php

curl --location --request POST 'BASE_URL/v3/logistics/freight-distance' --header 'x-api-key: API_KEY' --header 'Content-Type: application/json' --data-raw '{
	"trip_id": "TRIP_1001",
	"customer_identifier": "CUST_001",
	"customer_industry": "Retail",
	"service_type": "FTL",
	"freight_segment": "Primary",
	"load_type": "General",
	"teu": 0,
	"trip_timestamp": 1706745600,
	"shipment_weight": {
		"weight_value": 2000,
		"weight_unit": "KGS"
	},
	"trip_weight": {
		"weight_value": 2400,
		"weight_unit": "KGS"
	},
	"address": {
		"origin_address": "Mumbai, Maharashtra, India",
		"destination_address": "Delhi, India"
	},
	"distance": {
		"distance_travelled": 1400,
		"distance_unit": "Kms"
	},
	"vehicle": {
		"vehicle_identifier": "MH12AB1234",
		"vehicle_ownership": "Owned",
		"vehicle_code": "HGV4",
		"vehicle_fueltype": "Diesel",
		"vehicle_make": "Tata",
		"vehicle_name": "Prima",
		"vehicle_engine_type": "Diesel",
		"vehicle_make_year": 2022
	},
	"shipment_sequence": 1,
	"is_trip_empty": false,
	"customer_items_count": 150,
	"total_items_count": 220,
	"empty_distance_included": false,
	"country": "INDIA"
}'

const fetch = require('node-fetch');

const url = 'BASE_URL/v3/logistics/freight-distance';
const apiKey = 'API_KEY';

const headers = {
	'x-api-key': apiKey,
	'Content-Type': 'application/json'
};

const body = JSON.stringify({
	trip_id: 'TRIP_1001',
	customer_identifier: 'CUST_001',
	customer_industry: 'Retail',
	service_type: 'FTL',
	freight_segment: 'Primary',
	load_type: 'General',
	teu: 0,
	trip_timestamp: 1706745600,
	shipment_weight: {
		weight_value: 2000,
		weight_unit: 'KGS'
	},
	trip_weight: {
		weight_value: 2400,
		weight_unit: 'KGS'
	},
	address: {
		origin_address: 'Mumbai, Maharashtra, India',
		destination_address: 'Delhi, India'
	},
	distance: {
		distance_travelled: 1400,
		distance_unit: 'Kms'
	},
	vehicle: {
		vehicle_identifier: 'MH12AB1234',
		vehicle_ownership: 'Owned',
		vehicle_code: 'HGV4',
		vehicle_fueltype: 'Diesel',
		vehicle_make: 'Tata',
		vehicle_name: 'Prima',
		vehicle_engine_type: 'Diesel',
		vehicle_make_year: 2022
	},
	shipment_sequence: 1,
	is_trip_empty: false,
	customer_items_count: 150,
	total_items_count: 220,
	empty_distance_included: false,
	country: 'INDIA'
});

const options = {
	method: 'POST',
	headers: headers,
	body: body
};

fetch(url, options)
	.then(response => response.json())
	.then(data => {
		console.log(data);
	})
	.catch(error => {
		console.error(error);
	});

var axios = require('axios');

var data = JSON.stringify({
	"trip_id": "TRIP_1001",
	"customer_identifier": "CUST_001",
	"customer_industry": "Retail",
	"service_type": "FTL",
	"trip_timestamp": 1706745600,
	"shipment_weight": {
		"weight_value": 2000,
		"weight_unit": "KGS"
	},
	"trip_weight": {
		"weight_value": 2400,
		"weight_unit": "KGS"
	},
	"address": {
		"origin_address": "Mumbai, Maharashtra, India",
		"destination_address": "Delhi, India"
	},
	"distance": {
		"distance_travelled": 1400,
		"distance_unit": "Kms"
	},
	"vehicle": {
		"vehicle_ownership": "Owned",
		"vehicle_code": "HGV4",
		"vehicle_fueltype": "Diesel"
	},
	"customer_items_count": 150,
	"total_items_count": 220,
	"country": "INDIA"
});

var config = {
	method: 'post',
	url: 'BASE_URL/v3/logistics/freight-distance',
	headers: {
		'x-api-key': 'API_KEY',
		'Content-Type': 'application/json'
	},
	data: data
};

axios(config)
.then(function (response) {
	console.log(JSON.stringify(response.data));
})
.catch(function (error) {
	console.log(error);
});

import requests
import json

url = "BASE_URL/v3/logistics/freight-distance"

payload = json.dumps({
	"trip_id": "TRIP_1001",
	"customer_identifier": "CUST_001",
	"customer_industry": "Retail",
	"service_type": "FTL",
	"trip_timestamp": 1706745600,
	"shipment_weight": {
		"weight_value": 2000,
		"weight_unit": "KGS"
	},
	"trip_weight": {
		"weight_value": 2400,
		"weight_unit": "KGS"
	},
	"address": {
		"origin_address": "Mumbai, Maharashtra, India",
		"destination_address": "Delhi, India"
	},
	"distance": {
		"distance_travelled": 1400,
		"distance_unit": "Kms"
	},
	"vehicle": {
		"vehicle_ownership": "Owned",
		"vehicle_code": "HGV4",
		"vehicle_fueltype": "Diesel"
	},
	"customer_items_count": 150,
	"total_items_count": 220,
	"country": "INDIA"
})

headers = {
'x-api-key': 'API_KEY',
'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();

$request->setUrl('BASE_URL/v3/logistics/freight-distance');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setConfig(array(
	'follow_redirects' => TRUE
));
$request->setHeader(array(
	'x-api-key' => 'API_KEY',
	'Content-Type' => 'application/json'
));
$request->setBody('{
  "trip_id": "TRIP_1001",
  "customer_identifier": "CUST_001",
  "customer_industry": "Retail",
  "service_type": "FTL",
  "trip_timestamp": 1706745600,
  "shipment_weight": {
    "weight_value": 2000,
    "weight_unit": "KGS"
  },
  "trip_weight": {
    "weight_value": 2400,
    "weight_unit": "KGS"
  },
  "address": {
    "origin_address": "Mumbai, Maharashtra, India",
    "destination_address": "Delhi, India"
  },
  "distance": {
    "distance_travelled": 1400,
    "distance_unit": "Kms"
  },
  "vehicle": {
    "vehicle_ownership": "Owned",
    "vehicle_code": "HGV4",
    "vehicle_fueltype": "Diesel"
  },
  "customer_items_count": 150,
  "total_items_count": 220,
  "country": "INDIA"
}');

try {
	$response = $request->send();
	if ($response->getStatus() == 200) {
		echo $response->getBody();
	} else {
		echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
		$response->getReasonPhrase();
	}
} catch (HTTP_Request2_Exception $e) {
	echo 'Error: ' . $e->getMessage();
}

Sample Response

Below are sample responses for the above request.

Responses

Success - 200
Failure - 400
Failure - 500

{
  "success": true,
  "message": "Logistic data saved successfully",
  "data": {
    "id": 12456,
    "trip_id": "TRIP-001",
    "idempotency_key": "TRIP-001_1",
    "trip_timestamp": 1719206400,
    "trip_date": "2024-06-24T00:00:00.000Z",
    "service_type": "FTL",
    "freight_segment": "",
    "load_type": "",
    "teu": 0,
    "shipment_weight_value": 2000,
    "shipment_weight_unit": "KGS",
    "trip_weight_value": 2200,
    "trip_weight_unit": "KGS",
    "origin_address": "Mumbai",
    "destination_address": "Delhi",
    "distance_travelled_value": 1420.5,
    "distance_travelled_unit": "Kms",
    "vehicle_type": "Truck",
    "vehicle_identifier": "MH12AB1234",
    "vehicle_ownership": "Own",
    "vehicle_code": "HGV2",
    "vehicle_fueltype": "Diesel",
    "vehicle_make": "Tata",
    "vehicle_name": "Prima",
    "vehicle_engine_type": "BS6",
    "vehicle_make_year": 2022,
    "shipment_sequence": 1,
    "is_trip_empty": false,
    "customer_items_count": 10,
    "total_items_count": 10,
    "empty_distance_included": false,
    "country": "INDIA",
    "customer_id": 789,
    "client_id": "client_123",
    "total_emission_value": 345.12,
    "total_emission_unit": "kgCO2e",
    "total_activity_value": 2841000,
    "total_activity_unit": "kg.km",
    "well_to_tank_emission_value": 52.3,
    "well_to_tank_emission_unit": "kgCO2e",
    "tank_to_wheel_emission_value": 292.82,
    "tank_to_wheel_emission_unit": "kgCO2e",
    "emission_intensity_value": 0.1215,
    "emission_intensity_unit": "kgCO2e/kg.km",
    "payload_capacity": 0,
    "mode_of_transport": "Road",
    "createdAt": "2026-02-24T10:45:12.000Z",
    "updatedAt": "2026-02-24T10:45:12.000Z"
  }
}

{
  "success": false,
  "message": "\"vehicle.vehicle_code\" must be one of [SCD, LCV1, HGV2, HGV4, ACF, LCV2, LCV3, ACB, HGV, TRAIN]"
}

{
  "success": false,
  "message": "Failed to calcuate emissions"
}

Freight Distance

Request Parameters​

Endpoint​

Method​

Headers​

Payload​

Field Validation​

Required fields​

Optional fields​

Enum / limited values​

Notes​

Response Parameters​

Status Code​

Response Data​

Sample Request​

Sample Response​