Home → Blog

Freight Rate API: Developer Guide (US FTL + Limited Ocean/Air)

March 16, 2026 · 9 min read · By FreightPulse Engineering

Building a logistics app without rate data is painful. FreightPulse’s /api/v1/freight-rates is a thin wrapper over Warp’s public quote API. The live path is US full-truckload. Ocean and air exist only for a short list of Asia origins into a US ZIP — and Warp often returns “priced by our team” instead of a number.

What the Endpoint Does

Default mode is trucking. Auth is the X-API-Key header. Always send Accept: application/json. Missing ZIPs do not 422 — you get 200 with available: false.

curl "https://freightpulsehq.com/api/v1/freight-rates?mode=trucking&origin_zip=10001&destination_zip=90210" \
  -H "X-API-Key: your_api_key" \
  -H "Accept: application/json"

Successful FTL shape:

{
  "success": true,
  "data": {
    "mode": "trucking",
    "service": "FTL (53' dry van)",
    "source": "Warp",
    "price_usd": 7208,
    "transit_days": 4,
    "pickup_date": "2026-08-24",
    "delivery_date": "2026-08-28",
    "valid_until": "2026-08-21T18:00:00Z"
  }
}

If Warp cannot quote the lane:

{
  "success": true,
  "data": {
    "mode": "trucking",
    "available": false,
    "note": "Missing required parameter(s): origin_zip, destination_zip"
  }
}

Ocean and Air (Limited)

Use mode=ocean or mode=air with origin_country and dest_zip. Allowed origins: China, Vietnam, India, Taiwan, South Korea. Example:

curl "https://freightpulsehq.com/api/v1/freight-rates?mode=ocean&origin_country=China&dest_zip=90210" \
  -H "X-API-Key: your_api_key" \
  -H "Accept: application/json"

There is no origin=CNSHA / destination=USLAX pair API. LOCODE-to-LOCODE ocean indexes are not in v1. When Warp has no live tier, available is false and the note often says the lane needs a team quote.

Integration Patterns That Work

1. Quote a US lane

Collect two ZIP codes, call trucking, render price_usd and transit_days when available is not false. Cache 15–30 minutes — Warp is rate-limited (~60 req/hour per origin IP on the shared key).

2. Rate change alerts

There are no webhooks. Poll a small set of lanes on a cron and diff price_usd yourself.

3. Historical rates

There is no /freight-rates/history. /historical stores national EIA diesel/gasoline and daily port-congestion series for ~20 curated ports — do not chart ocean TEU rate history from this API.

Mode Nuances

• Trucking — FTL 53' dry van, US ZIP to US ZIP. Live when Warp has a quote.
• Ocean / air — Asia origin country + US dest ZIP. Often unavailable.
• Rail — not a mode.

Quality Checks

• Always branch on available — a 200 is not a price.
• Source field — live quotes say Warp.
• Coverage — confirm your lanes in the playground before promising them in your UI.

Error Handling

• No quote — available: false, still 200. Show a fallback, do not treat it as 404.
• 429 — back off. Quota headers are on authenticated JSON responses.
• 422 — validation (for example invalid mode). Envelope is {success: false, error, errors?}.

Auth

API key in X-API-Key. Not OAuth. Store keys in env vars. Rotate from the dashboard. There is no IP allowlist product feature.

SDKs

There are no official npm, pip, or Go packages. Use fetch / requests / HTTP clients. Anything named @freightpulse/sdk is not ours.

Pricing

Free: 100 calls/month. Basic $49 (1,000), Pro $99 (10,000), Business $299 (25,000), Enterprise $499 (100,000). Calls are shared across all endpoints, not a dedicated rate SKU.

No credit card to register.

What's Next

• API documentation — real parameters and envelopes
• Port congestion — PortWatch activity index, not wait time
• Disruptions — live natural-hazard events (GDACS, USGS, NOAA/NWS); no geopolitical or port-closure coverage