Basic Benchmark
Get market rate benchmarks for freight routes.
POST /benchmark/basicReturns the market rate benchmark for a freight route, including median rate, average rate, and confidence score.
Cost: 1 credit (€0.03 overage)
Permission required: benchmark:basic
Request
Headers
| Header | Required | Description |
|---|---|---|
Authorization | Yes | Bearer cb_live_xxxxxxxxxxxx |
Content-Type | Yes | application/json |
Body Parameters
| 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 (e.g., "Warsaw") |
dest_city | string | No | Destination city name (e.g., "Berlin") |
origin_zip | string | No | Origin postal code (e.g., "00-001") |
dest_zip | string | No | Destination postal code (e.g., "10115") |
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) |
Distance Required
The distance_km parameter is required for all benchmark requests. Distance is the most significant factor in freight pricing, and providing accurate distance ensures reliable market rate benchmarks.
Location Precision
For best results, provide the most specific location data you have:
- Postal codes = highest accuracy
- City names = good accuracy
- Country only = lowest accuracy
The API automatically falls back to less precise matching if exact matches aren't found.
Example Request
curl -X POST https://cargobloom.io/api/v1/benchmark/basic \
-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"
}'const response = await fetch('https://cargobloom.io/api/v1/benchmark/basic', {
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',
}),
});
const { success, data, error } = await response.json();import requests
response = requests.post(
'https://cargobloom.io/api/v1/benchmark/basic',
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',
}
)
data = response.json()Response
Success Response
{
"success": true,
"data": {
"median_rate_per_km": 1.25,
"avg_rate_per_km": 1.28,
"offer_count": 156,
"confidence": "high",
"search_method": "city"
},
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}Response Fields
| Field | Type | Description |
|---|---|---|
median_rate_per_km | number | Market median rate in EUR/km. Use this as your benchmark. |
avg_rate_per_km | number | Average rate in EUR/km (typically slightly higher than median) |
offer_count | integer | Number of offers used in calculation |
confidence | string | Data reliability indicator |
search_method | string | How the data was matched |
Confidence Levels
| Value | Meaning | Offer Count |
|---|---|---|
high | Reliable benchmark | 100+ offers |
medium | Good estimate | 30-99 offers |
low | Limited data | 1-29 offers |
none | No matching data | 0 offers |
Low Confidence Results
For low or none confidence, consider:
- Broadening your search (remove city/zip filters)
- Increasing
date_range_days - Using
vehicle_type: "ALL"
Search Methods
The API uses a fallback strategy to find the best match:
| Method | Description |
|---|---|
postal_code | Matched by exact postal code regions |
city | Matched by city names |
distance_range | Matched by similar distance routes |
country | Fell back to country-level data |
none | No matching data found |
Response Headers
Every response includes rate limit information:
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 9
X-RateLimit-Reset: 1706745600
X-Request-ID: 550e8400-e29b-41d4-a716-446655440000Error Responses
Validation Error
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "origin_country must be a 2-letter ISO country code",
"details": {
"field": "origin_country",
"received": "Poland"
}
},
"request_id": "..."
}Insufficient Permissions
{
"success": false,
"error": {
"code": "INSUFFICIENT_PERMISSIONS",
"message": "API key lacks required permission: benchmark:basic"
},
"request_id": "..."
}See Error Handling for all error codes.
Calculating Total Price
To estimate a total freight price:
const rate = data.median_rate_per_km; // e.g., 1.25
const distance = 575; // km
const estimatedPrice = rate * distance; // €718.75
// Add margin for negotiation (asking prices are typically 5-15% above final)
const conservativePrice = estimatedPrice * 0.90; // €646.88For pre-calculated price estimates, use the Detailed Benchmark endpoint.
Best Practices
-
Cache responses — Market rates don't change dramatically minute-to-minute. Cache for 15-60 minutes.
-
Use accurate distances — Distance is the most important pricing factor. Use routing APIs (Google Maps, HERE) to calculate accurate road distances rather than straight-line estimates.
-
Use specific locations — Postal codes give more accurate results than country-only queries.
-
Handle low confidence — When
confidenceislowornone, display a warning to users or fall back to broader parameters. -
Batch similar queries — If checking multiple similar routes, the Detailed Benchmark may be more cost-effective.
Related
- Detailed Benchmark — Extended data with percentiles, trends, and price estimates
- Vehicle Types — All supported vehicle/equipment types
- Country Codes — Supported countries and coverage levels
Last updated: February 3, 2026