Tutorial

Build a Freight Rate Comparison Tool with the ShippingRates API

2026-03-24 10 min read By ShippingRates

Build a Freight Rate Comparison Tool with the ShippingRates API

Freight logistics teams waste hours collecting demurrage schedules, comparing carrier tariffs, and estimating landed costs across spreadsheets. The ShippingRates API gives you programmatic access to carrier rates, port data, D&D charges, and total landed costs — so you can build a comparison tool that answers "which carrier is cheapest for this route?" in a single API call.

In this tutorial you will wire up a working rate-comparison workflow using curl. Every command is copy-paste ready. The free tier gives you 25 requests per month with zero signup, so you can follow along right now.

What You Will Build

Query the carrier and port database
Compare detention & demurrage (D&D) charges across every carrier for a country
Calculate full landed cost on a specific route
Connect the API to an AI agent via MCP for natural-language freight queries

Getting Started

The base URL for every request is:

https://api.shippingrates.org

The free tier includes 25 requests per month. No API key, no signup, no credit card. Just start making requests. When you need higher volume, paid endpoints use the x402 protocol — your HTTP client pays per-request with USDC on Base or Solana. More on that in the final section.

Full interactive documentation lives at api.shippingrates.org/docs.

Step 1: Explore Available Data

Start by checking what the database covers. The /api/stats endpoint returns counts for every data category.

curl https://api.shippingrates.org/api/stats

Sample response:

{
  "carriers": 28,
  "ports": 4892,
  "countries": 185,
  "dd_tariffs": 12740,
  "freight_rates": 38500,
  "exchange_rates": 45
}

Next, list all available carriers with /api/lines:

curl https://api.shippingrates.org/api/lines

Sample response:

{
  "lines": [
    "maersk",
    "msc",
    "cma-cgm",
    "hapag-lloyd",
    "cosco",
    "evergreen",
    "one",
    "yang-ming",
    "zim",
    "hmm"
  ]
}

These carrier slugs are what you pass to the rate and D&D endpoints.

Step 2: Search Ports

To build a comparison tool you need origin and destination port codes. The /api/search endpoint does a fuzzy search across port names, UN/LOCODE codes, and countries.

curl "https://api.shippingrates.org/api/search?keyword=mumbai"

Sample response:

{
  "results": [
    {
      "port_code": "INNSA",
      "port_name": "Nhava Sheva (JNPT)",
      "country": "India",
      "country_code": "IN"
    },
    {
      "port_code": "INBOM",
      "port_name": "Mumbai",
      "country": "India",
      "country_code": "IN"
    }
  ]
}

You can also check live exchange rates — useful when displaying costs in the shipper's local currency:

curl "https://api.shippingrates.org/api/fx?from=USD&to=INR"

{
  "from": "USD",
  "to": "INR",
  "rate": 83.42,
  "timestamp": "2026-03-24T00:00:00Z"
}

Step 3: Compare D&D Rates Across Carriers

This is the core of a comparison tool. The /api/dd/compare endpoint returns detention and demurrage charges from every available carrier for a given country, container type, and number of days. One request, all carriers.

curl -X POST https://api.shippingrates.org/api/dd/compare \
  -H "Content-Type: application/json" \
  -d '{
    "country": "IN",
    "container_type": "40HC",
    "days": 14
  }'

Sample response:

{
  "country": "IN",
  "container_type": "40HC",
  "days": 14,
  "comparison": [
    {
      "line": "maersk",
      "total_cost_usd": 490,
      "free_days": 7,
      "charged_days": 7,
      "daily_breakdown": [
        { "day_range": "1-7", "daily_rate": 0, "type": "free" },
        { "day_range": "8-14", "daily_rate": 70, "type": "detention" }
      ]
    },
    {
      "line": "msc",
      "total_cost_usd": 560,
      "free_days": 4,
      "charged_days": 10,
      "daily_breakdown": [
        { "day_range": "1-4", "daily_rate": 0, "type": "free" },
        { "day_range": "5-14", "daily_rate": 56, "type": "detention" }
      ]
    },
    {
      "line": "cma-cgm",
      "total_cost_usd": 420,
      "free_days": 7,
      "charged_days": 7,
      "daily_breakdown": [
        { "day_range": "1-7", "daily_rate": 0, "type": "free" },
        { "day_range": "8-14", "daily_rate": 60, "type": "detention" }
      ]
    }
  ]
}

Sort the comparison array by total_cost_usd and you have an instant cheapest-carrier ranking. This endpoint costs $0.25 per call on the paid tier.

If you only need a single carrier, use /api/dd/calculate instead ($0.10 per call):

curl -X POST https://api.shippingrates.org/api/dd/calculate \
  -H "Content-Type: application/json" \
  -d '{
    "line": "maersk",
    "country": "IN",
    "container_type": "40HC",
    "days": 14
  }'

Step 4: Calculate Landed Cost

D&D is only part of the picture. The /api/total-cost endpoint returns a full landed-cost breakdown for a specific carrier and route — freight, surcharges, origin/destination charges, and D&D combined.

curl "https://api.shippingrates.org/api/total-cost?line=maersk&origin=INNSA&destination=AEJEA&container_type=40HC"

Sample response:

{
  "line": "maersk",
  "origin": "INNSA",
  "destination": "AEJEA",
  "container_type": "40HC",
  "total_landed_cost_usd": 2340,
  "breakdown": {
    "ocean_freight": 1650,
    "origin_charges": 280,
    "destination_charges": 310,
    "surcharges": 100
  }
}

Pair this with /api/rates ($0.03 per call) to get raw freight rates across multiple carriers on the same lane:

curl "https://api.shippingrates.org/api/rates?origin=INNSA&destination=AEJEA"

Combine /api/dd/compare with /api/total-cost calls per carrier and you have a complete cost-comparison dashboard.

Step 5: Connect via MCP for AI Agent Integration

If you are building an AI agent that answers freight questions in natural language, you can connect the ShippingRates API as an MCP (Model Context Protocol) server. This lets tools like Claude Desktop, Cursor, or any MCP-compatible client call the API directly.

Add this to your MCP client configuration (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "shippingrates": {
      "url": "https://mcp.shippingrates.org/mcp"
    }
  }
}

Once connected, your AI agent can call tools like search_ports, compare_dd, calculate_landed_cost, and get_rates without you writing any glue code. Ask it:

"Compare D&D charges for a 40HC container in India across all carriers at 14 days"
"What is the landed cost from Nhava Sheva to Jebel Ali on Maersk?"
"Which carrier has the most free days for detention in Germany?"

The MCP server exposes the same endpoints documented above, wrapped as callable tools with typed parameters.

Going Further

Paid Endpoints and x402 Payment

After your 25 free requests, paid endpoints return an HTTP 402 Payment Required response with an x402 protocol payment header. Your client pays the per-request fee in USDC (on Base or Solana), and the request completes automatically. No subscription, no monthly invoice — you pay only for what you use.

Endpoint pricing summary:

Endpoint	Cost per Request
`POST /api/dd/calculate`	$0.10
`POST /api/dd/compare`	$0.25
`GET /api/total-cost`	$0.15
`GET /api/rates`	$0.03

Ideas for Your Comparison Tool

Carrier scorecards — Combine D&D compare + landed cost across your top 5 trade lanes to rank carriers by total cost.
Slack or Teams bot — Connect via MCP and let ops teams query rates in natural language from chat.
Rate alerts — Poll /api/rates periodically and notify when a lane drops below a threshold.
Multi-currency dashboards — Use /api/fx to convert everything to the shipper's home currency.

Resources

Compare Shipping Rates Across 8 Carriers

D&D calculator, rate comparator, and port intelligence — for humans and machines. 25 free API requests/month.

Open Dashboard Explore the API