SeaRates-compatible Container Tracking

Specification and collection

These are SeaRates' own documents with the server URL swapped, so an existing SDK, Postman collection or Swagger client re-points and works unchanged.

Response statuses

Every response is HTTP 200, including every refusal — SeaRates answer this way and their OpenAPI document declares exactly one response on all seven operations. message is the enum you branch on. Four values ride on status: "success": they are real answers about a real shipment, not failures. Every error also carries detail, our own sentence about the cause, in a field SeaRates do not define and any client will ignore.

The means column is what the refusal would be on a REST-shaped API. We do not send it — it is what we record, and it tells you whose problem a refusal is: the 4xx rows are yours to fix, the 5xx rows are ours or a carrier's. The one status that is not 200 is 405, for a verb other than GET, which never reaches an endpoint at all.

Retry-After is sent, in seconds, on the four refusals worth waiting out — a 200 may carry the header. API_KEY_LIMIT_REACHED and API_KEY_EXPIRED send 3600, and both mean stop retrying and fix billing: the call cannot succeed until you do. API_KEY_RATE_LIMIT and SEALINE_NO_RESPONSE send a real number of seconds. API_KEY_ACCESS_DENIED means developer mode is off on your account — turn it on in your dashboard settings.

SEALINE_NO_RESPONSE is the carrier, not us. When one line is down rather than the whole provider, data.metadata.sealine names it and detail says so — track the reference with a different carrier, or wait.

Differences from SeaRates

Everything else is their shape. These are not, and each is deliberate:

• GET /history — one entry per call, as SeaRates count them, and ?id= returns the document that call was answered with. It starts where our request logging does: calls made before this surface began writing access-log rows were never recorded, so an older reference has a list shorter than its age. The documents are all still there — the early calls are not countable, and dating them by guesswork would be worse than a short list.
• type=BK — accepted, and answered as BK. A booking is looked up through the bill-of-lading path, which is what our carrier feed accepts, so a line that resolves bookings only on a booking-typed lookup may report nothing found.
• AIS — we hold no vessel positions from AIS. ais is accepted and ignored, and route_data.ais is never present.
• vessel.call_sign and vessel.flag — present, always null. Our carrier feed does not send them, and an empty field beats a guess.
• /info/sealines optional fields — each line carries name and scac_codes. active, active_types, maintenance and prefixes are absent: we do not hold them per carrier, and a key we omit says "unknown" where false would say something we never learned. Filter on presence in the list, not on active.

Not a difference: absent is not null

A truck leg has no vessel key and an event the carrier never dated has no date key. SeaRates send the same — their published examples omit vessel on every leg without one. It is written down here because it disagrees with their SCHEMA, which types both as non-nullable, not because it disagrees with them. A field they always send and we cannot fill is null instead, as above. Nothing is invented either way.