API Reference

Try it — live sandbox

Run a real request against the API right now — no API key or sign-up needed. The sandbox returns fixed sample data (it doesn't touch your account or live carriers), so you can see the exact request and response shape before you integrate.

Authentication

All API requests must include your API key as a Bearer token in the Authorization header. You can generate and manage API keys from the Developer section of your dashboard.

Authorization: Bearer YOUR_API_KEY

Base URL

All endpoints are relative to the following base URL:

https://traqocontainer.com/api/v1

Errors

All error responses return JSON with a consistent structure:

{
  "statusCode": 401,
  "statusMessage": "Invalid or missing API key"
}

A 402 includes a structured data object so you can react programmatically. When data.error is "payment_overdue", tracking is paused because a payment failed and the grace period ended — update billing at data.manageUrl to resume (your existing shipments are unaffected):

{
  "statusCode": 402,
  "statusMessage": "Payment overdue — API access is paused. Update your billing to resume tracking.",
  "data": {
    "error": "payment_overdue",
    "overdueDays": 9,
    "graceDays": 7,
    "plan": "business",
    "manageUrl": "https://traqocontainer.com/dashboard/billing"
  }
}

Shipment limits

Two independent limits apply: a request rate limit per API key (see API rate limits) and a shipment slot limit — how many shipments your account can track simultaneously, set by your plan.

Each call to /api/v1/container/:number, /api/v1/bl/:number checks whether the shipment is already in your account. If it is, the call succeeds without consuming a slot. If it's new and you have remaining slots, it's added. If you've reached your limit, the API returns 402.

API rate limits

Every authenticated request is rate-limited per API key, in a fixed one-minute window. The default is 120 requests per minute (some plans allow more — check the headers below for your actual limit).

Every response carries your current budget, so you never have to guess:

Exceed the limit and you get a 429 with a Retry-After. Back off for that many seconds — retrying sooner just burns another 429:

{
  "success": false,
  "statusCode": 429,
  "message": "Rate limit exceeded — 120 requests per minute. Retry after 42s.",
  "data": { "error": "rate_limit_exceeded", "limit": 120, "retryAfter": 42 }
}

Track a container

Returns full tracking data for a container number — status, route, ETA, port events, and vessel info. Pass the container number directly in the URL. The shipment is automatically saved to your account in the background.

Path parameters

Query parameters

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://traqocontainer.com/api/v1/container/MRSU6859427?sealine=MAEU"

Response

Track a bill of lading

Returns full tracking data for a Bill of Lading number. Identical response structure to the container endpoint. The shipment is automatically saved to your account in the background.

Path parameters

Query parameters

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://traqocontainer.com/api/v1/bl/SHZ8037930?sealine=CMDU"

Response

Bulk track shipments

Track up to 50 containers or bills of lading in a single request — the batch form of the container and BL endpoints. Each item needs its 4-character SCAC (sealine). New shipments are saved to your account and consume a slot each; ones you already track are re-fetched for free.

Request body

Example request

curl -X POST https://traqocontainer.com/api/v1/track \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"shipments":[{"type":"container","number":"MRSU6859427","sealine":"MAEU"},{"type":"bl","number":"MEDUFR123456","sealine":"MSCU"}]}'

Response

List tracked shipments

Returns a paginated list of all shipments saved to your account — containers and bills of lading — with their current status, route, and ETA. Useful for building dashboards and monitoring multiple shipments at once.

Query parameters

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://traqocontainer.com/api/v1/shipments?page=1&pageSize=20"

Response

Get a shipment

Returns the current summary of a single shipment you already track — status, route, ETA and last_synced_at — straight from Traqo's stored data. Unlike /container and /bl, this never re-fetches from the carrier and never consumes a shipment slot, so it's the right call for cheap status checks and reconciliation. The {id} is the shipment id returned by /api/v1/shipments.

Example request

curl https://traqo.io/api/v1/shipments/MSCU1234567 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

When predictive ETA is enabled for your plan, the data object also carries predictive_eta and demurrage_risk — see Predictive ETA.

Untrack a shipment

Removes a shipment from your account and frees the slot it occupied, exactly like removing it from your dashboard. This is a soft delete — the shipment stops counting toward your monthly limit and disappears from /api/v1/shipments.

Example request

curl -X DELETE https://traqo.io/api/v1/shipments/MSCU1234567 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "deleted": true,
  "shipment_id": "MSCU1234567"
}

Track a vessel

Returns real-time AIS position, speed, heading, and voyage information for a vessel. Both imo (7 digits) and mmsi (9 digits) are required.

Query parameters

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://traqocontainer.com/api/v1/vessel/track?imo=9811000&mmsi=636022327"

Response

Voyage schedules

Returns sailing schedules between two ports for a given date, across available carriers.

Query parameters

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://traqocontainer.com/api/v1/voyage/schedules?origin=INMUN&destination=AEJEA&date=2026-06-01&week_range=2&date_type=departure"

Response

Port congestion

Returns the latest congestion score for a port (UN/LOCODE) plus its 90-day score history: an explainable 0–100 score, a bucket (fluid / normal / moderate / high / critical), a data-sufficiency tier (A/B/C), a 7-day trend, and the per-signal components (dwell, anchorage wait, ETA-slip, schedule deviation, bunching) with each signal's raw value, baseline and z-score.

Requires port-congestion to be enabled on your plan. Reads Traqo's own analytics — no upstream call, so it never consumes a shipment slot.

Predictive ETA on container tracking

When predictive ETA is enabled for your account, /api/v1/container/:number responses include a predictive_eta object: p50 and p80 timestamps, a source (model / blend / carrier), a confidence (high / medium / low), and computed_at. It's derived from live vessel progress plus port congestion — a more accurate arrival estimate than the raw carrier ETA, which goes stale.

Congestion board

Returns the current congestion reading for every scored port in one call — the same score / bucket / tier as the per-port endpoint, plus a 7-day trend_7d, a 30-day calls_30d volume, and coordinates. Use it to build a map or a watchlist without polling ports one at a time.

Same gating as Port congestion: requires port-congestion on your plan. Reads Traqo's own analytics — no upstream call, no shipment slot.

Example request

curl https://traqo.io/api/v1/ports/congestion \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

Search ports

A directory lookup against Traqo's port database — resolve a UN/LOCODE, port name, or city to canonical metadata (locode, name, city, country, region, coordinates). Handy for turning free-text origin/destination into the locodes the congestion and schedule endpoints expect. Local read, no upstream call.

Query parameters

Example request

curl "https://traqo.io/api/v1/ports?search=rotterdam" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

Resolve the carrier for a reference

Which carrier moves a given container or bill of lading — without tracking it. Creates no shipment, writes nothing, and consumes no shipment slot, so it is safe to call before you commit to tracking. Use it to fill the sealine on /track, or to reconcile a carrier against your own master data.

Query parameters

Confidence

Every candidate carries a confidence, because the sources are not equally strong. Treat it as the difference between a value you can file against and one you should verify.

“We don’t know” vs “we couldn’t ask”

Both look like carrier: null, and they call for opposite responses — so sources_unavailable tells you which one you got. It lists the sources that errored or ran past the 3-second resolution budget. Empty is the healthy case.

Two rules worth coding against

• carrier is null if and only if candidates is empty. There is no confidence floor — a low-confidence winner is still returned as carrier. If you only want strong answers, filter on confidence yourself; don’t assume we did.
• candidates is always an array, never null and never absent — possibly empty.

Limits

This endpoint has its own daily cap per API key, separate from the per-minute rate limit, because each new reference fans out to identification lookups on our side. The default is 1,000 lookups per key per day.

Over the cap you get a 429 that says when it lifts. Note the error code — it’s how you tell this cap apart from the per-minute limit, which returns rate_limit_exceeded and lifts within the minute:

{
  "success": false,
  "statusCode": 429,
  "message": "Carrier lookup limit reached — 1000 lookups per day. Resets at 2026-08-26T09:14:00.000Z (retry after 41230s). Repeat lookups of a reference you already resolved do not count against this.",
  "data": {
    "error": "lookup_limit_exceeded",
    "limit": 1000,
    "retryAfter": 41230,
    "resetAt": "2026-08-26T09:14:00.000Z"
  }
}

Example request

curl "https://traqocontainer.com/api/v1/carriers/lookup?number=MRKU8636841" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

List supported carriers

The directory of every ocean carrier Traqo can track, each with its 4-character scac and name. This is the lookup you need before calling /container, /bl or /track: the scac returned here is exactly what you pass as the optional sealine parameter. Local read — never consumes a shipment slot.

Query parameters

Example request

curl "https://traqocontainer.com/api/v1/carriers?search=maersk" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

Webhooks

Instead of polling, subscribe to events and we'll POST them to your server as they happen — a shipment's status or ETA changes, or carrier auto-discovery recovers a shipment that first failed to track. Register and manage endpoints from the Webhooks tab of your dashboard; you can subscribe each endpoint to specific events or to all of them.

Every delivery is a JSON POST with the same envelope — an event name, a created unix timestamp (seconds), and an event-specific data object:

{
  "event": "shipment.updated",
  "created": 1754170000,
  "data": {
    "shipment_id": "SHP-000481",
    "reference_number": "MSCU1234567",
    "carrier": "MSCU",
    "status": "IN_TRANSIT",
    "previous_status": "BOOKED",
    "eta": "2026-08-14T09:00:00.000Z",
    "previous_eta": "2026-08-12T09:00:00.000Z"
  }
}

Request headers

Delivery & retries

Acknowledge a delivery by responding with any 2xx status within 10 seconds — respond first, then do your processing asynchronously. Any non-2xx response, or a timeout, is retried with exponential backoff (≈30s, 1m, 2m, 4m … capped at 6h) up to the configured attempt limit, after which the delivery is marked failed.

Webhook events

Subscribe an endpoint to any of these events, or to * for all of them.

The three shipment events share the data shape shown in the envelope above (status/previous_status carry the transition; eta/previous_eta the ETA move). discovery.recovered carries the recovered carrier:

{
  "reference_number": "MSCU1234567",
  "type": "Container",
  "carrier": "MSCU",
  "carrier_name": "MSC",
  "shipment_id": "SHP-000481"
}

Verifying signatures

Every delivery is signed so you can confirm it came from Traqo and wasn't tampered with. The X-Traqo-Signature header has a timestamp and a signature:

X-Traqo-Signature: t=1754170000,v1=5f3b1a…c9d2

v1 is the HMAC-SHA256, as lowercase hex, of the string <t>.<raw request body>, keyed with your endpoint's signing secret (whsec_…, shown once when you create or rotate the endpoint). To verify: recompute the HMAC over t + "." + the raw body, compare it to v1 in constant time, and reject anything whose t is more than a few minutes (300s) from now to stop replay.

import { createHmac, timingSafeEqual } from 'node:crypto'

// Capture the RAW body for this route (do NOT let a JSON parser consume it first):
//   app.post('/webhooks/traqo', express.raw({ type: 'application/json' }), handler)

function verify(rawBody, header, secret, toleranceSec = 300) {
  const parts = Object.fromEntries(header.split(',').map(s => s.split('=')))
  const t = Number(parts.t)
  if (!t || !parts.v1) return false
  if (Math.abs(Math.floor(Date.now() / 1000) - t) > toleranceSec) return false
  const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex')
  const a = Buffer.from(parts.v1, 'hex'), b = Buffer.from(expected, 'hex')
  return a.length === b.length && timingSafeEqual(a, b)
}

app.post('/webhooks/traqo', (req, res) => {
  const raw = req.body.toString('utf8')
  if (!verify(raw, req.get('X-Traqo-Signature'), process.env.TRAQO_WEBHOOK_SECRET)) {
    return res.sendStatus(400)
  }
  const { event, data } = JSON.parse(raw)
  res.sendStatus(200)          // ack fast, then process asynchronously
  // … handle `event` (dedupe on the X-Traqo-Delivery header) …
})

What’s new

Changes to the public API, newest first. Everything here is additive — new optional parameters and new response fields. No request that worked before has stopped working, and no field has been removed or changed type. Code defensively against fields you don’t recognise and you can adopt these at your own pace.