Detailed Benchmark
Extended market analysis with percentiles, trends, and price estimates.
POST /benchmark/detailedReturns comprehensive market analysis including rate percentiles, price estimates, supply/demand metrics, and historical trends.
Cost: 2 credits (€0.12 overage)
Permission required: benchmark:detailed
Request
Headers
| Header | Required | Description |
|---|---|---|
Authorization | Yes | Bearer cb_live_xxxxxxxxxxxx |
Content-Type | Yes | application/json |
Body Parameters
All parameters from Basic Benchmark are supported, including the required distance_km parameter. The detailed endpoint uses the same request format but returns extended response data including percentiles, price estimates, supply/demand metrics, and market trends.
| Parameter | Type | Required | Description |
|---|---|---|---|
origin_country | string | Yes | Origin country ISO code (e.g., "PL") |
dest_country | string | Yes | Destination country ISO code (e.g., "DE") |
distance_km | number | Yes | Route distance in km (1-5000) |
origin_city | string | No | Origin city name |
dest_city | string | No | Destination city name |
origin_zip | string | No | Origin postal code |
dest_zip | string | No | Destination postal code |
distance_tolerance_km | number | No | Acceptable distance variance (10-500, default: 100) |
vehicle_type | string | No | Equipment type (default: "ALL") |
date_range_days | number | No | Historical data window (1-365, default: 7) |
Example Request
curl -X POST https://cargobloom.io/api/v1/benchmark/detailed \
-H "Authorization: Bearer cb_live_xxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"origin_country": "PL",
"dest_country": "DE",
"origin_city": "Warsaw",
"dest_city": "Berlin",
"distance_km": 575,
"vehicle_type": "CURTAIN_SIDER",
"date_range_days": 30
}'const response = await fetch('https://cargobloom.io/api/v1/benchmark/detailed', {
method: 'POST',
headers: {
'Authorization': 'Bearer cb_live_xxxxxxxxxxxx',
'Content-Type': 'application/json',
},
body: JSON.stringify({
origin_country: 'PL',
dest_country: 'DE',
origin_city: 'Warsaw',
dest_city: 'Berlin',
distance_km: 575,
vehicle_type: 'CURTAIN_SIDER',
date_range_days: 30,
}),
});
const { success, data } = await response.json();import requests
response = requests.post(
'https://cargobloom.io/api/v1/benchmark/detailed',
headers={'Authorization': 'Bearer cb_live_xxxxxxxxxxxx'},
json={
'origin_country': 'PL',
'dest_country': 'DE',
'origin_city': 'Warsaw',
'dest_city': 'Berlin',
'distance_km': 575,
'vehicle_type': 'CURTAIN_SIDER',
'date_range_days': 30,
}
)
data = response.json()Response
Full Response Example
{
"success": true,
"data": {
"median_rate_per_km": 1.25,
"avg_rate_per_km": 1.28,
"offer_count": 156,
"confidence": "high",
"search_method": "city",
"min_rate": 0.95,
"max_rate": 1.85,
"percentile_25": 1.12,
"percentile_75": 1.42,
"estimated_price_eur": {
"median": 719,
"avg": 736,
"range_low": 644,
"range_high": 816
},
"supply_demand": {
"supply_count": 245,
"demand_count": 312,
"ratio": 0.79,
"market_condition": "supply_shortage",
"data_available": true
},
"trends": {
"change_24h": 2.5,
"change_7d": -1.2,
"change_30d": 5.8
},
"filters_applied": {
"origin_country": "PL",
"dest_country": "DE",
"origin_city": "Warsaw",
"dest_city": "Berlin",
"distance_km": 575,
"vehicle_type": "CURTAIN_SIDER",
"date_range": ["2026-01-02", "2026-02-01"]
}
},
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}Response Fields
Use Cases
Freight Auditing
Check if a quoted price is fair:
const quote = 850; // EUR quoted by carrier
const { median, range_low, range_high } = data.estimated_price_eur;
if (quote < range_low) {
console.log('Quote is below market - suspiciously cheap');
} else if (quote > range_high) {
console.log('Quote is above market - negotiate down');
} else {
console.log('Quote is within market range');
}Rate Forecasting
Use trends to predict direction:
const { change_24h, change_7d, change_30d } = data.trends;
// Simple momentum indicator
const momentum = (change_24h + change_7d + change_30d) / 3;
if (momentum > 2) {
console.log('Rates trending strongly upward');
} else if (momentum < -2) {
console.log('Rates trending downward');
} else {
console.log('Rates relatively stable');
}Capacity Planning
Use supply/demand data:
const { ratio, market_condition } = data.supply_demand;
if (market_condition === 'supply_shortage') {
console.log('Book capacity early - market is tight');
} else if (market_condition === 'supply_surplus') {
console.log('Can negotiate - plenty of capacity available');
}When to Use Detailed vs Basic
| Use Case | Recommended Endpoint |
|---|---|
| Quick rate check | Basic (1 credit) |
| Price validation/auditing | Detailed (2 credits) |
| Building price ranges | Detailed (2 credits) |
| Trend analysis | Detailed (2 credits) |
| High-volume API calls | Basic (1 credit) |
| User-facing rate display | Basic (1 credit) |
| Internal decision support | Detailed (2 credits) |
Related
- Basic Benchmark — Simpler, cheaper alternative
- Market API — Overall market indicators
- Vehicle Types — All supported equipment types
Last updated: February 3, 2026