Getting started
The Tracking One API is one REST interface over ocean and air cargo tracking. You send a container, bill of lading, booking or air waybill number; you get back the shipment's current status, the milestones it has passed, the vessels or flights and ports or airports on its route, and an estimated arrival — as JSON in the same shape whichever carrier or airline is behind it.
Everything is a plain GET over HTTPS with query parameters. There is nothing to install, no SDK you have to use, and no session to keep: an API key on the request is the whole protocol.
Base URL
https://api.tracking.one
Every path on this site is relative to it, and every path carries its major version:
| Endpoint | What it does | Key required |
|---|---|---|
GET /v1/shipments/ocean | Track a container, bill of lading or booking number | yes |
GET /v1/carriers/ocean | List the ocean carriers we track, and how each can be looked up | no |
GET /v1/shipments/air | Track an air waybill | yes |
GET /v1/carriers/air | List the airlines we track, with the prefix each issues | no |
The two carrier endpoints are open and free — they are coverage data, not tracking, so they are the natural thing to call while you are still wiring up.
Your first request
1. Check coverage, without a key
Start here, because it needs nothing from you but a terminal:
curl "https://api.tracking.one/v1/carriers/ocean"
The response lists the carriers we track and the lookup methods each one accepts. Not every line answers to all three kinds of number, and some need a container number alongside a bill of lading or a booking — this is where an integration finds that out, before it spends a request on a number a carrier cannot answer.
2. Get an API key
Create one in your dashboard. It is shown once, at creation. Authentication covers how to send it, where to keep it, and how to replace it.
3. Track a shipment
curl -H "Authorization: Bearer $TRACKING_ONE_API_KEY" \
"https://api.tracking.one/v1/shipments/ocean?referenceNumber=MEDU9270627"
referenceNumber is the only required parameter. Send carrierCode when you already know the line, and referenceType when you know which of the three kinds of number you are holding — both are optional, and leaving them off lets the carrier be detected from the number itself. Add routeDetails=true when you want the route drawn: segments, coordinates and, for a container currently on the water, AIS vessel data.
Air works the same way, with an AWB in number:
curl -H "Authorization: Bearer $TRACKING_ONE_API_KEY" \
"https://api.tracking.one/v1/shipments/air?number=001-27868153"
An air waybill names its airline in its own three-digit prefix, so there is no carrier parameter to send.
Every parameter, and the full response document, is on the endpoint's own page: Get Ocean Shipment and Get Air Shipment.
How responses come back
Success is 200 and a JSON document. Everything else is a status code and a JSON body with a message you can log, and — where there is something a client can act on — an error slug beside it.
| Status | What it means |
|---|---|
200 | The shipment document. |
202 | Accepted, not ready. See below. |
401 | No key, or a key that is invalid, expired or revoked. |
402 | Out of credits, or a usage cap reached. The body says which. |
429 | Rate limit. Retry-After says how long to wait. |
5xx | Something on our side, or an upstream carrier we could not reach. |
202 is not an error. Some carriers are slow, and a lookup can outlive the request that asked for it. Rather than hold the connection open until it dies, we answer 202 with
{ "message": "Request accepted and is being processed." }
The request was accepted and is running; repeat it in a few minutes and the answer will be there. A 202 is never billed, and the shipment number stays billable for the retry — so a client that treats 202 as "try again shortly" rather than as a failure costs nothing extra.
Rate limits
Requests are limited per API key: 100 requests every 20 seconds by default. The open carrier endpoints are limited per IP instead, since they carry no key.
Over the limit you get 429 and a Retry-After header with the number of seconds to wait. Honour it rather than retrying immediately — a tight retry loop just keeps the window full.
If your integration needs a higher ceiling, tell us what shape the traffic is and we can raise it on your account.
What a lookup costs
A shipment is billed once per calendar month, however many times you ask about it. The first successful lookup of a number is charged; every repeat of the same number that month is free and returns the current data.
So polling a container that is still moving costs no more than looking it up once, and there is no reason to build a cache in front of us to save money. Errors are not charged either — a 4xx, a 5xx or a 202 is refunded automatically. The pricing page has the current terms.
Versioning
The version is in the path. Everything documented here is v1, and v1 will not change shape underneath you: new fields and new endpoints get added, existing fields do not get renamed or removed. A change that would break a client goes in a new version with its own prefix.
Write your client so unknown fields in a response are ignored rather than rejected, and additions will never reach you as an outage.
OpenAPI documents
Every page on this site is generated from OpenAPI 3.0 documents, and those are published as they are — import one into Postman or Insomnia, or point a generator at it for a typed client.
Where to go next
- Authentication — API keys, how to send them, and what to do when one leaks.
- Container Tracking API — ocean endpoints, parameters and responses.
- Air Tracking API — the same for air waybills.
- Tracking widgets — drop-in trackers for your own site, if you would rather not build the front end.
- OpenAPI specification — the machine-readable documents, for Postman, Insomnia or a generated client.
Something not covered here? Talk to support.