RESTful API v1.0

Developer API

Integrate shipment tracking and published ocean schedules into your applications

API Documentation View Endpoints Sailing schedules guide

Carrier Data

Direct carrier integrations with regular ocean and air cargo updates

Secure & Reliable

API-key authentication, HTTPS endpoints, and account-based access controls

Webhook Support

Receive shipment and container events with webhook support.

Bulk Operations

Track up to 100 containers or AWBs in a single API call with batch processing support

Build with sailing schedules

Search published ocean carrier schedules by route, vessel, port or service. Every result carries source and freshness information.

Try schedule search
  1. Check current coverage

    Read /v1/ext/carriers for carrier codes and available search capabilities. Tracking coverage and schedule coverage are different.

  2. Search a date window

    Use UN/LOCODEs for ports and a published carrier code. Send calendar dates as YYYY-MM-DD; both ends of a range are inclusive.

  3. Keep the publication context

    Display scheduleMetadata alongside the sailing. Preserve the source's date precision and show stale data explicitly.

Example: departures from Singapore to ShanghaiAuthenticated GET · illustrative query
curl --get 'https://api.trackcargo.co/api/schedule/sea/v1/point-to-point-routes' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'X-Schedule-Search-Id: YOUR_NEW_UUID' \
  --data-urlencode 'placeOfReceipt=SGSIN' \
  --data-urlencode 'placeOfDelivery=CNSHA' \
  --data-urlencode 'departureStartDate=2026-11-09' \
  --data-urlencode 'departureEndDate=2026-11-23' \
  --data-urlencode 'limit=20'

Replace these example dates with your intended departure window. A matching sailing is not guaranteed.

Choose a search

Schedule base URL: https://api.trackcargo.co/api/schedule/sea. Every schedule plan includes API access. Use your account’s x-api-key header, or a signed-in session’s Authorization: Bearer token. Without authentication, only 3 lifetime guest searches per public IP are available.

SearchEndpoint and inputsDate filters
RouteGET /v1/point-to-point-routes

Required: placeOfReceipt, placeOfDelivery. Optional: carrierCode.

departureStartDate, departureEndDate, arrivalStartDate, arrivalEndDate
VesselGET /v1/vessel-schedules

Filter by vesselIMONumber (seven digits), or carrierCode with carrierVesselCode or exact vesselName. Service and voyage references are also supported.

startDate, endDate
PortGET /v1/port-schedules

Required: UNLocationCode, date. Optional carrier, service and facility filters.

date is the lower bound unless startDate is supplied. Optional endDate.
ServiceGET /v3/service-schedules

Filter by carrierCode, carrierServiceCode or universalServiceReference.

startDate, endDate

Responses and pagination

The four search endpoints return a JSON array, not a data envelope. Read API-Version, X-Schedule-Search-Id, X-Schedule-Remaining and Next-Page-Cursor from the response headers.

Send limit (1–500; default 100). For the next page, repeat the same filters and pass the returned cursor. Stop when there is no next cursor. If the publication changes and a cursor becomes invalid, restart from page one.

The default lower bound is today. Supply an explicit start date for reproducible queries.

One web and API allowance

Registered organisations receive 100 free searches per month. Paid plans increase the shared web and API allowance with hard limits and no automatic overages. Compare schedule plans.

Send a new UUID in X-Schedule-Search-Id for each logical search. Reuse it with identical filters for cursor pages and retries for up to one hour; after one hour start a new search with a new ID. A successful search, including an empty array, uses one credit. Errors do not.

Batch requests charge once per successful query. History, cutoff and terminal-detail endpoints each count as a search. Suggestions, carriers, coverage, access and the plan catalog do not consume searches.

GET /v1/ext/access returns a direct object with authenticated, planId, limit, used, remaining and resetsAt.

Quota errors expose a root code and access object alongside DCSA errors: SCHEDULE_REGISTRATION_REQUIRED (403), SCHEDULE_QUOTA_EXCEEDED (429) or SCHEDULE_SEARCH_IN_PROGRESS. Preserve your query and follow the corresponding registration, upgrade or retry path.

Published dates and provenance

scheduleMetadata includes provider, source, fetchedAt, expiresAt, freshness and coverage.

Preserve date-only, port-local and offset-specified timestamp precision. Do not convert a date-only value to midnight or label a port-local time as UTC. Inferred years are marked sourceYearInferred.

Optional vesselInsights contains locally stored Datalastic identity, vessel particulars and qualified AIS observations. Vessel-reported ETA and departure values are distinct from carrier dates. Optional calculatedCutOffTimes applies only a qualified, scoped carrier rule and carries its source, basis and timezone; published cutOffTimes remain separate.

These are carrier publications. They do not carry a measured ETA confidence score. Tracking predictions remain separate in the tracking API's date_ai field.

Empty results and errors

200 with []: no matching result in current published coverage. It does not establish that a commercial sailing does not exist.

400: invalid input or cursor. Check the response's errors entries before retrying.

503: no qualified publication is available for the requested carrier or capability. Keep this distinct from an empty successful search; check /v1/ext/coverage before retrying with backoff.

Read collection health

GET /v1/ext/coverage exposes jobs[].lastRun. Check success is (attempted - failed) / attempted; completed checks with empty or historical-only results count as successful checks. With no attempted checks, the percentage is unmeasured.

Optional deferred counts vessel checks that were not started, with grouped deferredReasons. These checks are excluded from the success denominator. For example, two attempted checks, one failure and nine deferred checks means 50% check success, with nine checks still pending. A missing deferred count does not establish zero pending work.

Read the run timestamps, publication freshness, source scope and catalogue progress together. A 100% check success rate does not establish complete carrier coverage or schedule accuracy; the response's observedAt is not the publication's refresh time.

What a schedule establishes

Coverage is a published source subset. Derived routes are marked same-vessel-published-rotation and bookingAvailability: not-verified. They do not establish bookable space or infer transshipment connections.

Assigned sailings are returned by default. includePendingVessels=true opts into explicitly unassigned route slots. For vessels, includePendingDates=true only retains undated calls when no date filters are supplied.

Vessel lookup, coverage, cutoffs, history and batch requests

Optional sourceDates preserves additional carrier fields such as estimated berth time and cargo pickup availability. Each value identifies its source field, label and clock semantics. These reference dates do not replace operational arrival/departure timestamps and are not evidence of an actual event. Carrier-specific closing fields are retained in sourceCutOffTimes when a standard cutoff code cannot be assigned confidently.

When published, each port call includes terminalCalls: an ordered list of terminal visits with facility codes and separate timestamps. Repeat visits remain separate. Port timestamps describe the overall port call; terminal timestamps describe each terminal visit. Both retain actual and estimated event classifiers. A terminal with dateQuality: invalid-source-chronology has reversed source date pairs: these are retained only in rejectedTimestamps for provenance and must not be used operationally. Valid pairs remain in timestamps.

  • GET /v1/ext/vessels?q=... — search published vessel names, IMOs or carrier codes with a literal term of 2–100 characters. Optional carrierCode, startDate, endDate and limit (1–30; default 12). Returns a direct object with items, hasMore and coverage; narrow the term when hasMore is true. This is not a global vessel directory.
  • GET /v1/ext/carriers — carrier identities, current capabilities and freshness, in the TrackCargo response envelope.
  • GET /v1/ext/coverage — a direct object with publication counts, refresh results and observation time.
  • GET /v1/ext/sailing/{transportCallReference}/cut-off — published cutoffs, in the TrackCargo response envelope.
  • GET /v1/ext/sailing/{transportCallReference}/history — observed changes, in the TrackCargo response envelope.
  • GET /v1/ext/port/{UNLocationCode}/terminals — facilities present in publications, in the TrackCargo response envelope.
  • POST /v1/ext/point-to-point-routes/batch — send 1–20 queries as {"queries": [{"placeOfReceipt": "SGSIN", "placeOfDelivery": "CNSHA"}]}; read each result's status and requestIndex in data.results. Use core GET pagination when you need all pages; batch responses do not expose next-page cursors.

Schedule webhook subscriptions are not available; the subscribe endpoint returns HTTP 501. Use paginated reads and sailing history.

Read the text API reference

API Endpoints

All endpoints use base URL https://api.trackcargo.co. Authenticated endpoints require an x-api-key header. Public endpoints marked (Public) do not require authentication.

Sea schedules (Web + API) API docs →

MethodEndpointDescription
GET/api/schedule/sea/v1/point-to-point-routes Search published routes by port pair, departure or arrival window, and carrier
GET/api/schedule/sea/v1/vessel-schedules Search vessel calls by IMO, carrier vessel code, service or voyage reference
GET/api/schedule/sea/v1/ext/vessels Find published vessels by name, IMO or carrier code for search suggestions
GET/api/schedule/sea/v1/port-schedules Search published calls at a UN/LOCODE, with carrier and facility filters
GET/api/schedule/sea/v3/service-schedules Search published service schedules by carrier and service reference
GET/api/schedule/sea/v1/ext/carriers Check carrier codes, currently available schedule capabilities and freshness
GET/api/schedule/sea/v1/ext/coverage Inspect source publication counts and refresh outcomes
POST/api/schedule/sea/v1/ext/point-to-point-routes/batch Run multiple port-pair queries with an individual outcome for each query

Orders API docs →

MethodEndpointDescription
POST/api/v1/client-orders/create Create a new client order
POST/api/v1/client-orders/create/tracking/sea Create and immediately initiate sea shipment tracking
POST/api/v1/client-orders/create/tracking/air Create and immediately initiate air shipment tracking
POST/api/v1/client-orders/create/bulk/tracking/sea Bulk-create sea tracking orders (up to 100 per request)
POST/api/v1/client-orders/create/bulk/tracking/air Bulk-create air tracking orders (up to 100 per request)
GET/api/v1/client-orders/{orderId} Get details for a specific order
GET/api/v1/client-orders/recent List most recent orders across all modes
GET/api/v1/client-orders/sea List all sea shipment orders
GET/api/v1/client-orders/air List all air shipment orders
GET/api/v1/client-orders/sea/overview Aggregated overview stats for sea shipments
GET/api/v1/client-orders/air/overview Aggregated overview stats for air shipments
PATCH/api/v1/client-orders/{orderId}/set-carrier Assign or update the carrier for an order
POST/api/v1/client-orders/{orderId}/cancel Cancel tracking for an order
DELETE/api/v1/client-orders/{orderId} Permanently delete an order
GET/api/v1/client-orders/{orderId}/tracking Get tracking data for an order (sea or air)

Carriers (Public)

MethodEndpointDescription
GET/api/tracking/api/v1/active-airlines List all supported airlines for air tracking
GET/api/tracking/api/v1/active-shipping-lines List all supported shipping lines for sea tracking

Ready to integrate?

Get your API key and start tracking shipments programmatically

Get API Access View Full Docs