Container Tracking API (1.0)

Download OpenAPI specification:Download

Overview

This API is part of the Container Tracking system of VesselFinder, offering the capability to track your container shipments both via the VesselFinder web solution and by integrating these API resources into your own systems.

The API provides comprehensive visibility into the transportation plan, including container events and vessel AIS positions.

There is an API Wrapper for PHP and Python for easier implementation.

Charging

The Container Tracking API is accessible upon purchasing a container package, with prices listed on this page. Once you purchase a container package, you can start using the Container Tracking API.

When you search for a container for the first time, your limit decreases by one. Subsequent searches for the same container will not further decrease your limit. This allows you to continue monitoring your container shipments without incurring additional costs after the initial query, ensuring efficient and affordable tracking of your shipments.

Caching

Every successful request to the Container Tracking API is cached in our system for a period of 12 hours, so there is no need to query the same shipment more frequently than once per 12 hours.

The caching affects only the shipment data, but the ship's position is updated with the latest information received from the AIS system.

Get your API key

You can find your personal API key in the "Container Tracking" section of your VesselFinder Profile page.

API Endpoint

https://container.vesselfinder.com/api/1.0

Statuses

The API uses various status types in the JSON response body to indicate the success, failure, or pending status of a request. The following table provides detailed information about each status:

Status	Description
`success`	The request was successful.
`queued`	The request has been accepted and is queued.
`processing`	The request is currently being processed.
`error`	Error response with additional details.

Errors

The API uses standard HTTP status codes to indicate the success or failure of the API call. The body of the response will be JSON in the following format:

{
  "status": "error",
  "errorCode": "API_KEY_EXPIRED",
  "errorDescription": "API key is expired!"
}

Only errors with HTTP status codes 402 and 409 will include a subscription object in the JSON response.

{
  "status": "error",
  "errorCode": "INVALID_CONTAINER_NUMBER",
  "errorDescription": "Invalid container number.",
  "subscription": {
    "containersRemaining": 22,
    "expirationDate": 1738360799
  },
}

Error codes

Error Code	HTTP Code	Description
`WRONG_PARAMETERS`	`400`	Your request parameters are wrong or missing!
`API_KEY_RATE_LIMIT`	`400`	Too frequent requests!
`API_KEY_INVALID`	`401`	Your API key is invalid or expired!
`API_KEY_CONTAINER_LIMIT`	`402`	You have reached your container limit. Please contact us!
`AUTO_CANT_DETECT_SEALINE`	`409`	Were unable to automatically determine the shipping line.
`INVALID_CONTAINER_NUMBER`	`409`	Invalid container number.
`NO_CONTAINERS`	`409`	Request completed successfully. The line did not provide container information.
`NO_EVENTS`	`409`	Request completed successfully. The line provided information on container, but did not provide information on events.
`SEALINE_CANCELED_SHIPMENT`	`409`	Request completed successfully. Shipment cancelled.
`SEALINE_HASNT_PROVIDE_INFO`	`409`	Request completed successfully. The line replied that nothing was found for this request.
`SEALINE_NOT_SUPPORTED`	`409`	Shipping line is not supported.
`SEALINE_NO_RESPONSE`	`409`	An error occurred while executing the request. The line is not responding.
`SEALINE_TEMPORARY_DISABLED`	`409`	The requested shipping line is temporarily disconnected.
`SEALINE_UNDER_MAINTENANCE`	`409`	Support for the requested shipping line is in maintenance status.
`WRONG_SEALINE`	`409`	Invalid carrier alpha code (SCAC) specified.
`UNEXPECTED_ERROR`	`409`	Unexpected error, please contact us!

Event codes

This reference table provides informantion for all possible events during the container's voyage.

Code	Description
`LTS`	Land transshipment
`BTS`	Barge transshipment
`CEP`	Container empty to shipper
`CPS`	Container pickup at shipper
`CGI`	Container arrival at first POL (Gate in)
`CLL`	Container loaded at first POL
`VDL`	Vessel departure from first POL
`VAT`	Vessel arrival at T/S port
`CDT`	Container discharge at T/S port
`TSD`	Transshipment Delay
`CLT`	Container loaded at T/S port
`VDT`	Vessel departure from T/S
`VAD`	Vessel arrival at final POD
`CDD`	Container discharge at final POD
`CGO`	Container departure from final POD (Gate out)
`CDC`	Container delivery to consignee
`CER`	Container empty return to depot
`UNK`	Unknown

Tracking by container number

path Parameters

apiKey required	string Your API key.
containerNumber required	string = 11 characters Example: MEDU6965343 Container number.
sealine	string [ 2 .. 4 ] characters Default: "AUTO" Example: MSCU Standard Carrier Alpha Code (SCAC).

Responses

Response samples

Content type

application/json

{"status": "success",
"subscription": {"containersRemaining": 22,
"expirationDate": 1738360799
},
"general": {"containerNumber": "MEDU6965343",
"carrier": "Mediterranean Shipping Company (MSC)",
"updatedAt": 1716796519,
"cacheExpires": 1716839719,
"progress": 66,
"origin": {"date": 1713733200,
"country": "CN",
"locode": "CNYTN",
"name": "Yantian",
"latitude": 22.58333,
"longitude": 114.26667
},
"destination": {"date": 1720213200,
"country": "BG",
"locode": "BGBOJ",
"name": "Burgas",
"latitude": 42.50606,
"longitude": 27.46781
},
"currentLocation": {"vessel": {"imo": 9754965,
"mmsi": 636017577,
"name": "MSC REEF",
"latitude": -5.20396,
"longitude": -5.21485,
"course": 323.9,
"speed": 18.3,
"aisTimestamp": 1718014545
}
}
},
"points": [{"date": 1713733200,
"country": "CN",
"locode": "CNYTN",
"name": "Yantian",
"latitude": 22.58333,
"longitude": 114.26667,
"events": [{"date": 1713733200,
"code": "CEP",
"description": "Container empty to shipper"
},
{"date": 1713906000,
"code": "CGI",
"description": "Container arrival at first POL (Gate in)"
},
{"date": 1714510800,
"code": "CLL",
"description": "Container loaded at first POL",
"vessel": {"name": "MSC ILENIA",
"imo": 9962548,
"mmsi": 636023270
}
}
]
},
{"date": 1715115600,
"country": "SG",
"locode": "SGSIN",
"name": "Singapore",
"latitude": 1.28967,
"longitude": 103.85007,
"events": [{"date": 1715115600,
"code": "CDT",
"description": "Container discharge at T/S port",
"vessel": {"name": "MSC ILENIA",
"imo": 9962548,
"mmsi": 636023270
}
},
{"date": 1716238800,
"code": "CLT",
"description": "Container loaded at T/S port",
"vessel": {"name": "MSC REEF",
"imo": 9754965,
"mmsi": 636017577
}
}
]
},
{"date": 1719522000,
"country": "TR",
"locode": "TRTEK",
"name": "Tekirdag",
"latitude": 40.9781,
"longitude": 27.51101,
"events": [{"date": 1719522000,
"code": "VAT",
"description": "Vessel arrival at T/S port",
"vessel": {"name": "MSC REEF",
"imo": 9754965,
"mmsi": 636017577
}
}
]
},
{"date": 1720213200,
"country": "BG",
"locode": "BGBOJ",
"name": "Burgas",
"latitude": 42.50606,
"longitude": 27.46781,
"events": [{"date": 1720213200,
"code": "VAD",
"description": "Vessel arrival at final POD"
}
]
}
]
}