API Reference

The FreightTrackAPI REST API. All responses are JSON. Billed per API call.

Authentication

All API requests require an API key passed via the x-api-key header. You can create and manage keys in your dashboard.

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

Base URL

https://api.freighttrackapi.com

Endpoints

Method	Path	Auth	Description
`GET`	/track/{bookingNumber}	x-api-key	Track by carrier booking or reference number
`GET`	/	None	API info (name, version, environment)
`GET`	/health	None	Health check

GET /track/{bookingNumber}

Resolves the carrier from the booking number format and returns voyage steps. Responses are cached for 24 hours.

Path parameters

Parameter	Type	Description
`bookingNumber`	string	The booking or reference number issued by the carrier (OOCL example: 2751234567)

Supported carriers

COSCO, Evergreen, Maersk, OOCL, ZIM, ANL, ONE, Shipco. The carrier is resolved automatically from the booking number format — no need to specify it.

Example request

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

Example response

{
  "bookingNumber": "2751234567",
  "mode": "ocean",
  "carrier": "OOCL",
  "cached": false,
  "fetchedAt": "2024-11-01T08:00:00.000Z",
  "expiresAt": "2024-11-02T08:00:00.000Z",
  "steps": [
    {
      "stepIndex": 0,
      "modeOfTransport": "VESSEL",
      "vesselName": "OOCL EXAMPLE VESSEL",
      "voyageNumber": "042E",
      "portOfLoadingCode": "CNSHA",
      "portOfLoadingName": "Shanghai",
      "portOfDischargeCode": "USNYC",
      "portOfDischargeName": "New York",
      "etd": "2024-10-20T14:00:00.000Z",
      "eta": "2024-11-10T08:00:00.000Z"
    }
  ]
}

Response fields

Field	Type	Description
`bookingNumber`	string	The booking number as provided
`mode`	"ocean" \| "air"	Transport mode (currently always ocean)
`carrier`	string	Resolved carrier code (e.g. COSCO, MAERSK, ZIM)
`cached`	boolean	true if this response was served from cache
`fetchedAt`	ISO 8601	When the data was fetched from the carrier
`expiresAt`	ISO 8601	When the cache entry expires (24h TTL)
`steps`	array	Ordered voyage legs — see Step object below

Step object

Field	Type	Description
`stepIndex`	number	Zero-based leg index
`modeOfTransport`	"VESSEL" \| "TRUCK" \| "RAIL" \| "UNKNOWN"	Transport mode for this leg
`vesselName`	string \| null	Vessel name (when modeOfTransport is VESSEL)
`voyageNumber`	string \| null	Voyage number
`portOfLoadingCode`	string \| null	UN/LOCODE for port of loading
`portOfLoadingName`	string \| null	Human-readable port of loading name
`portOfDischargeCode`	string \| null	UN/LOCODE for port of discharge
`portOfDischargeName`	string \| null	Human-readable port of discharge name
`etd`	ISO 8601 \| null	Estimated time of departure
`eta`	ISO 8601 \| null	Estimated time of arrival

Error codes

Status	Description
`400`	Bad request — unknown, ambiguous, or disabled carrier, or malformed booking number
`401`	Unauthorized — missing or invalid x-api-key header
`429`	Too Many Requests — rate limit exceeded
`500`	Internal Server Error — upstream carrier error or unexpected failure

Error response shape

{
  "statusCode": 401,
  "message": "Unauthorized"
}

Billing & rate limits

FreightTrackAPI is billed per successful API call — you are only charged when the API returns a 2xx response.

Rate limits are enforced per API key. If you hit a 429, implement exponential backoff before retrying. Contact us at hello@freightapi.com if you need a higher limit.