Cargo Prices, Freight Market Intelligence & Analytics

This guide will walk you through making your first API request to get a freight market benchmark.

Prerequisites

A Cargobloom account (sign up)
A tool to make HTTP requests (cURL, Postman, or any programming language)

Create an API Key

Go to the Developer Console
Click Create Key
Give your key a name (e.g., "Development")
Select permissions:
- benchmark:basic — Required for /benchmark/basic
- benchmark:detailed — Required for /benchmark/detailed
- market:read — Required for /market
Copy your API key immediately — it won't be shown again

Your key will look like: cb_live_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Test Keys

For development, create a key starting with cb_test_. Test keys return mock data and don't consume credits.

Make Your First Request

Let's get the market rate for a 575 km freight route from Poland to Germany:

curl -X POST https://cargobloom.io/api/v1/benchmark/basic \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "origin_country": "PL",
    "dest_country": "DE",
    "distance_km": 575
  }'

const response = await fetch('https://cargobloom.io/api/v1/benchmark/basic', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    origin_country: 'PL',
    dest_country: 'DE',
    distance_km: 575,
  }),
});

const result = await response.json();

if (result.success) {
  console.log(`Market rate: €${result.data.median_rate_per_km}/km`);
  console.log(`Based on ${result.data.offer_count} offers`);
} else {
  console.error(`Error: ${result.error.message}`);
}

import requests
import os

response = requests.post(
    'https://cargobloom.io/api/v1/benchmark/basic',
    headers={
        'Authorization': f'Bearer {os.environ["CARGOBLOOM_API_KEY"]}',
        'Content-Type': 'application/json',
    },
    json={
        'origin_country': 'PL',
        'dest_country': 'DE',
        'distance_km': 575,
    }
)

result = response.json()

if result['success']:
    data = result['data']
    print(f"Market rate: €{data['median_rate_per_km']}/km")
    print(f"Based on {data['offer_count']} offers")
else:
    print(f"Error: {result['error']['message']}")

Distance Required

The distance_km parameter is required. Distance is the most significant factor in freight pricing—benchmarks without distance aren't meaningful.

Understand the Response

A successful response looks like this:

{
  "success": true,
  "data": {
    "median_rate_per_km": 1.25,
    "avg_rate_per_km": 1.28,
    "offer_count": 156,
    "confidence": "high",
    "search_method": "country"
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Key fields:

Field	Description
`median_rate_per_km`	The market rate in EUR/km. Use this as your benchmark.
`offer_count`	Number of offers used to calculate the rate
`confidence`	Data quality: `high` (100+), `medium` (30-99), `low` (1-29)

Add More Precision

For better accuracy, add city names or postal codes alongside the required distance:

{
  "origin_country": "PL",
  "dest_country": "DE",
  "distance_km": 575,
  "origin_city": "Warsaw",
  "dest_city": "Berlin"
}

The API uses a fallback strategy to find matching offers:

First tries to match by postal code (most accurate)
Then by city name
Then by distance range (using your provided distance_km ± tolerance)
Finally by country pair

The search_method field tells you which method was used.

Calculate a Total Price

To estimate a total freight price, multiply the rate by distance:

const rate = data.median_rate_per_km;  // e.g., 1.25
const distance = 575;                   // km

const estimatedPrice = rate * distance; // €718.75

Or use the /benchmark/detailed endpoint which includes pre-calculated price estimates.

Next Steps

Authentication — Learn about API keys, permissions, and test mode
Credits & Pricing — Understand the billing model
Basic Benchmark API — Full endpoint documentation
Error Handling — Handle errors gracefully

Common Issues

"MISSING_API_KEY" Error

Make sure you're including the Authorization header:

Authorization: Bearer cb_live_sk_xxxxxxxxxxxx

"INVALID_API_KEY" Error

Check that:

Your key starts with cb_live_ or cb_test_
You copied the full key (no trailing spaces)
The key hasn't been revoked

"INSUFFICIENT_PERMISSIONS" Error

Your API key doesn't have the required permission. Go to the Developer Console and add the missing permission to your key.

Empty or Low Confidence Results

Some routes have limited data. Try:

Using just country codes without cities
Increasing date_range_days to 30 or 90
Setting vehicle_type to ALL

Last updated: February 3, 2026

This guide will walk you through making your first API request to get a freight market benchmark.

Prerequisites

A Cargobloom account (sign up)
A tool to make HTTP requests (cURL, Postman, or any programming language)

Create an API Key

Go to the Developer Console
Click Create Key
Give your key a name (e.g., "Development")
Select permissions:
- benchmark:basic — Required for /benchmark/basic
- benchmark:detailed — Required for /benchmark/detailed
- market:read — Required for /market
Copy your API key immediately — it won't be shown again

Your key will look like: cb_live_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Test Keys

For development, create a key starting with cb_test_. Test keys return mock data and don't consume credits.

Make Your First Request

Let's get the market rate for a 575 km freight route from Poland to Germany:

curl -X POST https://cargobloom.io/api/v1/benchmark/basic \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "origin_country": "PL",
    "dest_country": "DE",
    "distance_km": 575
  }'

const response = await fetch('https://cargobloom.io/api/v1/benchmark/basic', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    origin_country: 'PL',
    dest_country: 'DE',
    distance_km: 575,
  }),
});

const result = await response.json();

if (result.success) {
  console.log(`Market rate: €${result.data.median_rate_per_km}/km`);
  console.log(`Based on ${result.data.offer_count} offers`);
} else {
  console.error(`Error: ${result.error.message}`);
}

import requests
import os

response = requests.post(
    'https://cargobloom.io/api/v1/benchmark/basic',
    headers={
        'Authorization': f'Bearer {os.environ["CARGOBLOOM_API_KEY"]}',
        'Content-Type': 'application/json',
    },
    json={
        'origin_country': 'PL',
        'dest_country': 'DE',
        'distance_km': 575,
    }
)

result = response.json()

if result['success']:
    data = result['data']
    print(f"Market rate: €{data['median_rate_per_km']}/km")
    print(f"Based on {data['offer_count']} offers")
else:
    print(f"Error: {result['error']['message']}")

Distance Required

The distance_km parameter is required. Distance is the most significant factor in freight pricing—benchmarks without distance aren't meaningful.

Understand the Response

A successful response looks like this:

{
  "success": true,
  "data": {
    "median_rate_per_km": 1.25,
    "avg_rate_per_km": 1.28,
    "offer_count": 156,
    "confidence": "high",
    "search_method": "country"
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Key fields:

Field	Description
`median_rate_per_km`	The market rate in EUR/km. Use this as your benchmark.
`offer_count`	Number of offers used to calculate the rate
`confidence`	Data quality: `high` (100+), `medium` (30-99), `low` (1-29)

Add More Precision

For better accuracy, add city names or postal codes alongside the required distance:

{
  "origin_country": "PL",
  "dest_country": "DE",
  "distance_km": 575,
  "origin_city": "Warsaw",
  "dest_city": "Berlin"
}

The API uses a fallback strategy to find matching offers:

First tries to match by postal code (most accurate)
Then by city name
Then by distance range (using your provided distance_km ± tolerance)
Finally by country pair

The search_method field tells you which method was used.

Calculate a Total Price

To estimate a total freight price, multiply the rate by distance:

const rate = data.median_rate_per_km;  // e.g., 1.25
const distance = 575;                   // km

const estimatedPrice = rate * distance; // €718.75

Or use the /benchmark/detailed endpoint which includes pre-calculated price estimates.

Next Steps

Authentication — Learn about API keys, permissions, and test mode
Credits & Pricing — Understand the billing model
Basic Benchmark API — Full endpoint documentation
Error Handling — Handle errors gracefully

Common Issues

"MISSING_API_KEY" Error

Make sure you're including the Authorization header:

Authorization: Bearer cb_live_sk_xxxxxxxxxxxx

"INVALID_API_KEY" Error

Check that:

Your key starts with cb_live_ or cb_test_
You copied the full key (no trailing spaces)
The key hasn't been revoked

"INSUFFICIENT_PERMISSIONS" Error

Your API key doesn't have the required permission. Go to the Developer Console and add the missing permission to your key.

Empty or Low Confidence Results

Some routes have limited data. Try:

Using just country codes without cities
Increasing date_range_days to 30 or 90
Setting vehicle_type to ALL

Last updated: February 3, 2026

Quickstart

Prerequisites

Create an API Key

Make Your First Request

Understand the Response

Add More Precision

Calculate a Total Price

Next Steps

Common Issues

"MISSING_API_KEY" Error

"INVALID_API_KEY" Error

"INSUFFICIENT_PERMISSIONS" Error

Empty or Low Confidence Results

On this page

Quickstart

Prerequisites

Create an API Key

Make Your First Request

Understand the Response

Add More Precision

Calculate a Total Price

Next Steps

Common Issues

"MISSING_API_KEY" Error

"INVALID_API_KEY" Error

"INSUFFICIENT_PERMISSIONS" Error

Empty or Low Confidence Results

On this page