Examples

Practical code samples to get you integrated fast. Replace YOUR_API_KEY with the key from your dashboard.

Track a booking with curl

curl https://api.freighttrackapi.com/track/2751234567 \
  -H "x-api-key: YOUR_API_KEY"

List available carriers

curl https://api.freighttrackapi.com/carriers \
  -H "x-api-key: YOUR_API_KEY"

Node.js / TypeScript

import fetch from "node-fetch"; // or use built-in fetch in Node 18+

const API_KEY = process.env.FREIGHTTRACK_API_KEY!;
const BASE_URL = "https://api.freighttrackapi.com";

async function track(bookingNumber: string) {
  const res = await fetch(`${BASE_URL}/track/${bookingNumber}`, {
    headers: { "x-api-key": API_KEY },
  });

  if (!res.ok) {
    const error = await res.json();
    throw new Error(`Tracking failed: ${error.message}`);
  }

  return res.json();
}

// Usage
const data = await track("2751234567");
console.log(`Carrier: ${data.carrier}`);
console.log(`Steps: ${data.steps.length}`);
data.steps.forEach((step: { stepIndex: number; portOfLoadingName?: string; portOfDischargeName?: string; eta?: string | null }) => {
  console.log(
    `  [${step.stepIndex}] ${step.portOfLoadingName} -> ${step.portOfDischargeName}`,
    `  ETA: ${step.eta ?? "unknown"}`
  );
});

Python

import os
import requests

API_KEY = os.environ["FREIGHTTRACK_API_KEY"]
BASE_URL = "https://api.freighttrackapi.com"

def track(booking_number: str) -> dict:
    response = requests.get(
        f"{BASE_URL}/track/{booking_number}",
        headers={"x-api-key": API_KEY},
    )
    response.raise_for_status()
    return response.json()

# Usage
data = track("2751234567")
print(f"Carrier: {data['carrier']}")
print(f"Steps: {len(data['steps'])}")
for step in data["steps"]:
    print(
        f"  [{step['stepIndex']}] {step.get('portOfLoadingName')} -> {step.get('portOfDischargeName')}"
        f"  ETA: {step.get('eta', 'unknown')}"
    )

Error handling

const res = await fetch("https://api.freighttrackapi.com/track/UNKNOWN123", {
  headers: { "x-api-key": "YOUR_API_KEY" },
});

if (!res.ok) {
  const body = await res.json().catch(() => ({}));
  switch (res.status) {
    case 400:
      // Unknown, ambiguous, or disabled carrier
      console.error("Bad request:", body.message);
      break;
    case 401:
      // Missing or invalid API key
      console.error("Unauthorized — check your x-api-key header");
      break;
    case 429:
      // Rate limit exceeded
      console.error("Rate limit hit — back off and retry");
      break;
    default:
      console.error(`Unexpected error ${res.status}:`, body.message);
  }
}