To integrate a container tracking API into your logistics software, obtain API credentials, connect to the tracking endpoint, submit a container number or shipment reference, and map the returned data to your internal shipment records. Using a container tracking API such as Qubictron allows developers to retrieve carrier milestones, vessel details, route information, and estimated arrival times through a REST interface. Once the connection works, the next steps are storing shipment events, scheduling updates, handling API errors, and displaying accurate tracking information in your TMS, ERP, or customer portal.
This guide is written for logistics companies that want tracking inside their own software, whether a TMS, a forwarder's customer portal, or an internal operations dashboard. It follows the order in which teams usually meet the problems.
One expectation is worth setting early. Tracking through an API does not mean live GPS on every container. Ocean data is built mostly from reported events and vessel positions, so your software has to show what is confirmed, what is estimated, and when the information was last updated.
What the Integration Actually Covers
Online lookups and an API solve different problems. A browser search, even on the best online container tracking site, answers one person's question once. An integration answers your software's questions continuously, for every active shipment, without anyone typing in a number.
At the technical level, your system does three things: it registers shipments with a provider, receives updates, and turns those updates into information that staff and customers can use.
Intake: how containers, Bills of Lading, and bookings enter the tracking flow.
Update delivery: webhooks, polling, or a combination of both.
Business logic: how events change shipment records, alerts, and ETAs in your product.
A container tracking API sits between your records and the carriers' data. It does not replace your own shipment model; it feeds it.
A shipping container tracking system built on this foundation usually serves several teams at once. Operations wants exceptions, customer service wants a timeline it can quote, and finance may want arrival dates tied to storage risk. Decide who the first user is before designing the data model, because that choice determines which events you store and how quickly you need them.
Ocean container tracking API integration also differs from air or road work in a practical way. Ocean shipments move slowly, report milestones in irregular bursts, and pass through transshipment ports where the vessel, voyage, and even event wording change.
Before You Write Any Code
Decide Which References You Will Track
Tracking starts with an identifier, and your system probably holds more than one kind. Container numbers follow ISO 6346: three letters for the owner, a category letter (usually U), six digits, and a check digit. Validating that check digit on your side takes a few lines of code and prevents a whole class of failed requests caused by typos.
A Bill of Lading number identifies a transport document, so one B/L can return several containers. Booking numbers come from carriers in their own formats. Many providers also ask for the carrier's SCAC, the Standard Carrier Alpha Code, or can detect the carrier automatically. Check which references your provider accepts and which ones your data contains. If most bookings are created with B/L numbers, a container-only workflow will leave gaps.
Choose the Provider
Searching for the best container tracking API for logistics software usually starts with the wrong question. Which provider is best matters less than which one covers your carriers, trade lanes, and reference types with data your team can trust. Run a sample of real shipments through two or three candidates, including a container with transshipment, one still at sea, and one already delivered.
Look at the integration surface as well: documentation quality, a sandbox, webhook support, error reporting, rate limits, and whether original carrier events are exposed next to normalized ones.
Some companies also want container, air cargo, and vessel schedule data from one source. Qubictron works in that wider logistics technology space, so it can be part of such a comparison. Whichever providers make the shortlist, the test is the same: does the service return reliable events for the shipments you actually move?
Container Tracking API Integration, Step by Step
The sequence below fits most providers, although endpoint names and details differ. Treat it as a map, and read your provider's for the exact calls.
Step 1: Get Credentials and a Test Environment
Request a key from your container tracking API provider and look for test tracking numbers or a sandbox. Store the key in a secrets manager or an environment variable, never in source code or a front-end bundle. Keep separate keys for testing and production so that a test run cannot use up live quota. Make one call from the command line before writing application code.
Step 2: Send Your First Container Tracking API Request
Most providers expect you to create a tracking request for each container, Bill of Lading, or booking, instead of asking for a status each time. Send the reference, the carrier code if you have it, and your own shipment ID. That internal ID matters because it is how an incoming update finds the right record in your database.
curl -G "https://api.qubictron.com/tracking/v1/ocean" \
-H "x-api-key: YOUR_API_KEY" \
--data-urlencode "reference_number=MSKU7868382" \
--data-urlencode "reference_type=container" \
--data-urlencode "carrier_code=maeu"
The field names above are illustrative. Every provider names them differently.
Step 3: Process the API Response and Shipment Data
After sending a tracking request, your application receives a JSON response containing the available shipment information. Qubictron's Container Tracking API can return carrier details, container movements, port locations, vessel information, and tracking events. Before saving these records, your application needs to determine whether the request succeeded and whether the carrier actually provided useful data.
Start by validating three elements:
- HTTP response: Check whether the request was accepted or failed because of authentication, invalid parameters, or another technical issue.
- Application status: Examine success and status_code. An HTTP 200 response does not necessarily mean that tracking information is available. For example, CARRIER_NO_RESPONSE indicates that the carrier did not provide the expected data.
- Shipment events: Confirm that the response contains usable milestones. A NO_EVENTS status may indicate a valid request without any reported transportation events.
Once these checks pass, match the returned container number or shipment reference to the corresponding record in your logistics software. Store relevant milestones, locations, and timestamps rather than replacing the entire shipment history with the latest status.
If information is missing, preserve the last confirmed event and display an appropriate message. A missing carrier update should not automatically be interpreted as a shipment delay.
Step 4: Configure Shipment Updates with Polling or Supported Webhooks
A single API request returns the latest available shipment information, but container movements can take weeks. Your software needs to check for new carrier milestones, vessel movements, and ETA changes throughout the journey.
Polling is the simplest approach. Your application sends requests at scheduled intervals and compares the responses with stored shipment data. Some providers also support webhooks, which deliver updates automatically when new information becomes available. Check your provider's documentation before implementing either method.
Regardless of the approach, follow three basic practices:
Avoid duplicate events: Compare incoming milestones with existing records before saving them.
Respect API limits: Adjust request frequency based on shipment activity and provider restrictions.
Track data freshness: Store the actual event timestamp separately from the last API refresh.
For completed shipments, reduce or stop unnecessary requests. This keeps the integration efficient without losing important tracking history.
Step 5: Normalize and Store Events
Carriers describe the same milestone in different words. Providers usually map these descriptions to a shared vocabulary, and many follow the DCSA Track and Trace standard, which groups events into shipment, transport, and equipment events and marks each as planned, estimated, or actual. Ask which model and version your provider uses, then design your tables around it.
Store events, not only the latest status. With event type, location, timestamp, the planned, estimated, or actual flag, and the provider's original text on file, you can rebuild a timeline, settle a dispute, and change your display logic without losing history.
Step 6: Connect Events to Your Workflows
Raw events have no value until they change something in your product. Common connections include:
Updating shipment status in the TMS.
Refreshing the ETA fields used for trucking and warehouse planning.
Creating an exception when an ETA moves beyond a set threshold.
Notifying customers through a portal or email.
Passing arrival and discharge dates to billing or free-time monitoring, where you hold that data.
Most delays in container tracking API integration come from this mapping work, not from the API calls themselves.
What to Store From Each Update
Field | Why it matters |
|---|---|
Reference and your shipment ID | Matches updates to your records |
Event type and planned/estimated/actual flag | Separates confirmed milestones from forecasts |
Location (port or terminal) | Supports routing and arrival planning |
Event timestamp | Shows when the event occurred, per the source |
Received-at timestamp | Measures how fresh your data is |
Vessel and voyage | Helps verify schedules |
Original carrier event text | Supports debugging and disputes |
Provider request or event ID | Enables deduplication and support tickets |
Errors, Limits, and Security
Plan for these cases from the start, because production traffic will produce all of them:
Invalid or unknown reference. Reject bad check digits before the request leaves your system.
Carrier not supported or no data yet. Show a clear state, not an empty timeline.
Rate limiting. An HTTP 429 response means slow down. Respect the Retry-After header when the provider sends it.
Timeouts and server errors. Retry with exponential backoff and some random jitter, and set a maximum number of attempts.
Webhook endpoint downtime. Keep a reconciliation job that compares your records with the provider's current data.
On security, keep keys on the server, rotate them, and keep them out of logs. Restrict the webhook endpoint with signature checks and, if the provider publishes IP ranges, an allowlist.
Testing Before Launch
Test with real shipments, including the awkward ones: transshipment, a B/L covering several containers, a delivered container with a full history, an invalid number, a duplicate webhook, a late ETA change, and a provider outage. Compare several results with the carrier's own site.
Before the integration goes live, run it alongside the manual process for a couple of weeks and log every mismatch. Some will be your own bugs. Others will show where the provider's data falls short, and it is better to learn that before customers do.
Treat container tracking software integration as a product feature with an owner, not a one-off project. Carriers change their portals, providers add or retire coverage, and your own model will grow. Monitor webhook failures, unmatched updates, and requests stuck in pending.
What Your Software Should Not Promise
Users read your screens as fact, so design them around the limits of the data:
Vessel position is not container position. AIS shows the ship, while the container's last confirmed event may be days old.
ETA is an estimate. Label it that way and show when it last changed.
Timing varies. Updates depend on carriers, terminals, and the provider, and some providers refresh on fixed intervals measured in hours.
Coverage differs. "No data available" and "no new events" are different messages.
Terminal details are patchy. Holds, fees, and last free day are not available for every terminal or provider.
A shipping container tracking system earns trust by being clear about what it knows and when it learned it.
Where to Start
Begin small: one provider, one reference type, one trade lane. Get registration, a webhook, and event storage working for that slice, then widen coverage. A container tracking API is only useful when your team trusts what it shows, and that trust comes from clean references, stored events, honest labels, and testing with real shipments.
Frequently Asked Questions
How long does it take to connect a container tracking API?
A first working request can take hours. A production-ready setup with webhooks, event mapping, error handling, and testing takes considerably longer, depending on your stack and provider.
Can I track containers by Bill of Lading number?
Many providers support it, though requirements differ by carrier. One B/L can return several containers, so your data model must handle a one-to-many relationship.
Do I need a separate integration for every shipping line?
Not necessarily. An aggregating provider offers one interface for many carriers, but you should verify its coverage for your lines. Carrier interfaces differ, and industry standards such as DCSA's help, but adoption varies.
What is the biggest risk in a container tracking API integration?
Treating the data as more certain than it is. Estimates, vessel positions, delayed events, and duplicate messages all look convincing on a dashboard, so store the event type and timestamps and show them.
Can the API give the exact GPS location of a container?
Usually not. Most ocean tracking combines container events with vessel positions from AIS. That shows where the ship is, not an independently confirmed position for each container.