Container Tracking API for Terminal49: Shipments, ETAs and Milestones

Read the ocean shipments and containers tracked in your Terminal49 account through the Terminal49 API with your own API key, as clean dataset rows: ETAs, arrivals, vessels, terminal holds, fees, last free days, milestones and route maps.

Terminal49 is a container tracking platform for importers, freight forwarders, customs brokers and drayage carriers. It tracks bills of lading, bookings and container numbers across the major ocean carriers (shipping lines / VOCCs), US terminals and North American Class I rail, and normalizes every milestone from empty out at origin to empty return at destination. This actor wraps the read only part of its documented API v2 on api.terminal49.com, so you can pull ETAs into Google Sheets, BI dashboards, ERP or TMS systems, demurrage and detention alerts, or AI agents without writing a JSON:API client. Bring your own API key.

BYOK, not live tested: every route, parameter and field comes from Terminal49's published OpenAPI definition (terminal49.com/docs/openapi.json) and API reference, checked on 2026-10-25. The routes were probed with an invalid key on the same day. The actor has not been run against a live Terminal49 key.

What it does

• Shipments: one row per tracked shipment with bill of lading or booking number, shipping line SCAC and name, port of lading and port of discharge (UN/LOCODE and name), final destination, POD vessel name, IMO and voyage, ETD, ATD, current ETA, original ETA, ATA and whether tracking is still active. Filter by number, free text, port, arrival window, creation date, voyage status, tags and tracking state.
• Containers: one row per container with ISO 6346 number, current status (on ship, available, picked up, empty returned and more), equipment type and size, holds and fees at the POD terminal, availability for pickup, last free day and import deadlines (terminal, line and rail), yard location, rail and inland milestones, plus its shipment's ports, ETA, vessel and the POD terminal name. Filter by status, carrier, port, arrival, last free day and holds or fees.
• Container transport events: the normalized past milestones of each container (empty out, full in, vessel loaded, departed, transshipment, arrived, discharged, rail loaded and unloaded, full out, empty in, last free day changes) with time, timezone, UN/LOCODE, port name, vessel and terminal.
• Container raw and estimated events: the carrier's own event list, including future estimated milestones, with the original carrier wording.
• Container route map: each GeoJSON feature of the container's route, ports in sequence with ETAs and ATAs, the current vessel position, past vessel tracks and estimated future paths (needs Terminal49 Routing Data).
• Tracking requests: what your account asked Terminal49 to track, with status, failed reason and retries, to find numbers that never started tracking.
• Shipping lines, Ports, Terminals, Vessels: supported carriers with SCACs and tracking support, ports by UN/LOCODE with coordinates and time zone, terminals with FIRMS, SMDG and BIC codes, and vessels by IMO with their latest position.
• Container numbers just work: in the event and route modes, give container numbers and the actor finds their Terminal49 IDs first, without charging for that lookup.
• Pay only for results: unknown numbers, empty lists and refused lookups are recorded as a free row that says why, never charged.

How to use it

1. In Terminal49, create an API key under Developers at app.terminal49.com/developers/api-keys. Reading data needs a paid API plan or the 7 day API trial; a free plan key can only create tracking requests.
2. Paste the key into the API key field (or set the DATA_API_KEY secret). It is sent only to api.terminal49.com in the Authorization: Token header and is removed from everything the actor logs.
3. Pick a mode, add filters, numbers or IDs, and start the run. Download the rows as JSON, CSV or Excel, or call the actor from your own code or a schedule.

Containers must already be tracked in your Terminal49 account (through its web app, its API or email). This actor never creates tracking requests, because each one starts paid tracking on your Terminal49 plan and a repeated run would file duplicates.

A missing or rejected key, a free plan key, or an account without the Routing Data feature ends the run cleanly with a status message that says what to change.

Input

Field	Modes	Description
mode	all	shipments (default), containers, transportEvents, rawEvents, containerRoute, trackingRequests, shippingLines, ports, terminals or vessels
shipmentNumbers, shipmentIds	Shipments	Bill of lading or booking numbers (exact), or Terminal49 shipment UUIDs
searchText	Shipments, Tracking requests	Prefix search on shipment, reference and container numbers
trackingState	Shipments, Containers	Any, actively tracked or tracking stopped
voyageStatus, tags, shipmentSort	Shipments	Arrived or on ship, your shipment tags, sort order
polCodes, podCodes	Shipments, Containers	Port of lading and port of discharge UN/LOCODEs
arrivalFrom, arrivalTo	Shipments, Containers	POD arrival window, actual or estimated
createdFrom, createdTo	Shipments, Containers, Tracking requests	Creation date window
containerNumbers, containerIds	Containers, events, route	ISO 6346 container numbers or Terminal49 container UUIDs
currentStatuses, carrierScacs, onlyHoldsOrFees, lfdFrom, lfdTo	Containers	Status, carrier SCAC, holds or fees, last free day window
requestStatus	Tracking requests	Created, pending, failed or cancelled (carrierScacs takes one SCAC here)
portCodes, terminalIds, vesselImos	Ports, Terminals, Vessels	What to look up
maxResults	all	Most rows to return and charge for
requestsPerMinute	all	Pacing; Terminal49 allows 100 requests per minute per key
apiKey	all	Your Terminal49 API key (secret)

Output

Every row has flat columns that are easy to filter: containerNumber, containerId, shipmentId, billOfLading, carrierScac, status, polLocode, podLocode, podEtaAt, podAtaAt, destinationLocode, vesselName, vesselImo, event, eventTime, locationLocode, locationName, terminalName, lastFreeDay, availableForPickup, featureType, latitude, longitude, name and code. The full Terminal49 record is kept in attributes, and its relationships as IDs in relationshipIds. Times are UTC, as Terminal49 stores them, with the matching IANA timezone in attributes. A refused or empty lookup has found set to false and a note with Terminal49's own words.

Example container row (values from the Terminal49 API reference samples):

{
    "mode": "containers",
    "modeLabel": "Containers",
    "recordType": "container",
    "query": "CAIU7432986",
    "found": true,
    "id": "55a700e4-7005-45a9-92fd-1ff38641dbd9",
    "containerNumber": "CAIU7432986",
    "containerId": "55a700e4-7005-45a9-92fd-1ff38641dbd9",
    "shipmentId": "02b1bd6f-407c-45bb-8645-06e7ee34e7e3",
    "billOfLading": "MEDUF5399896",
    "carrierScac": "MSCU",
    "status": "available",
    "polLocode": "FRLEH",
    "podLocode": "USNYC",
    "podEtaAt": null,
    "podAtaAt": null,
    "destinationLocode": "USIND",
    "vesselName": "MSC ANISHA R.",
    "vesselImo": "9227297",
    "lastFreeDay": "2024-07-07T04:00:00Z",
    "availableForPickup": true,
    "attributes": {
        "number": "CAIU7432986",
        "equipment_type": "dry",
        "equipment_length": 40,
        "equipment_height": "high_cube",
        "pod_discharged_at": "2024-06-22T04:00:00Z",
        "holds_at_pod_terminal": [],
        "fees_at_pod_terminal": [],
        "pod_rail_carrier_scac": "CSXT",
        "import_deadlines": { "pickup_lfd_terminal": "2024-07-07T04:00:00Z", "pickup_lfd_rail": null, "pickup_lfd_line": "2024-07-07T04:00:00Z" },
        "current_status": "available"
    },
    "relationshipIds": { "shipment": "02b1bd6f-407c-45bb-8645-06e7ee34e7e3", "pickup_facility": null, "pod_terminal": "b859f5c3-8515-41da-bf20-39c0a5ada887" },
    "retrievedAt": "2026-10-25T12:00:00.000Z",
    "note": null
}

Transport event rows carry event (such as container.transport.vessel_loaded), eventTime, locationLocode, locationName, vesselName and terminalName. Raw event rows carry the carrier's original_event in attributes and status set to actual or estimated. Route rows carry featureType (port, current_vessel, past_vessel_locations and estimated paths), the point coordinates and the full GeoJSON geometry in attributes.geometry.

Pricing

Event	Price	Charged for
shipment	0.01 USD	Each shipment
container	0.01 USD	Each container, with its shipment and terminal
tracking-event	0.005 USD	Each transport event or raw carrier event
route-feature	0.005 USD	Each route map feature
tracking-request	0.005 USD	Each tracking request
reference-record	0.005 USD	Each shipping line, port or terminal
vessel-position	0.01 USD	Each vessel with its latest position

Unknown numbers, empty lists, refused lookups and the container number to ID lookup are never charged. Your Terminal49 plan is billed separately by Terminal49.

FAQ

What is the Terminal49 API?

Terminal49 is a US container tracking company whose API v2 (api.terminal49.com/v2, JSON:API style) returns shipment and container data for bills of lading, bookings and container numbers across ocean carriers, US marine terminals and North American rail. Tracking starts with a tracking request; from then on Terminal49 keeps shipments, containers and their milestones up to date.

Do I need my own Terminal49 API key?

Yes. This is a bring your own key actor: it calls Terminal49 with your key, under your plan and its terms. Create the key under Developers in the Terminal49 web app. The full value is shown only once, so copy it when you create it.

Why does my key get refused even though it is valid?

Terminal49 free plan keys can only create tracking requests; every read endpoint answers 401 until the account has a paid API plan or the 7 day API trial. The run then ends with Terminal49's own message rather than failing.

Can this actor start tracking a new container?

No. Creating a tracking request is billable on your Terminal49 plan, so the actor stays read only. Track the container in Terminal49 first, then read it here by container number.

How do I get the ETA of a container or bill of lading?

Use Shipments with the bill of lading in Shipment numbers for the port of discharge ETA, original ETA and ATA, or Containers with the container number for the container's status plus its shipment's ETA. Raw and estimated events add the carrier's future estimated milestones.

How do I find containers about to hit their last free day?

Run Containers with a Last free day window (for example today to three days out), optionally Only containers with holds or fees, and the Available for pickup status. Each row carries lastFreeDay, the terminal, line and rail deadlines, holds and fees.

Where do vessel positions and route maps come from?

From Terminal49's Routing Data feature. Container route map returns ports, the current vessel position and past and predicted paths as GeoJSON; Vessels returns the latest AIS position by IMO for vessels on your tracked shipments. Without the feature Terminal49 answers 403 and the run ends with that message.

What are the rate limits?

Terminal49 allows 100 requests per minute per key on a rolling window. The actor paces itself at 60 per minute by default and honours Retry-After on a 429.

Keyword map

container tracking API, ocean container tracking, shipment tracking API, bill of lading tracking, booking number tracking, container ETA API, vessel ETA, port of discharge arrival, container milestones, container status API, demurrage and detention, last free day API, terminal holds and fees, US port container availability, container route map GeoJSON, vessel position by IMO, shipping line SCAC list, UN/LOCODE port lookup, Terminal49 API, Terminal49 container tracking, Terminal49 shipments.

Routes and verification

Wrapped GET routes: /shipments, /shipments/{id}, /containers, /containers/{id}, /containers/{id}/transport_events, /containers/{id}/raw_events, /containers/{id}/map_geojson, /tracking_requests, /shipping_lines, /ports/{id}, /terminals/{id}, /vessels/{imo}. All were probed on 2026-10-25 with a deliberately invalid key and answered Terminal49's 401 JSON:API envelope, while invented paths answered a bare 404, so every route above exists as documented. Response shapes, filters and fields are taken from the vendor's OpenAPI definition and reference examples, not from live data.

Licensing and data use

This actor works only with your own Terminal49 account and API key, and Terminal49's terms apply to everything it returns. Those terms forbid reselling the data or using it to build a competing service; they set no limit on how long you may keep results. This actor is not affiliated with or endorsed by Terminal49.