{ "openapi": "3.0.4", "info": { "title": "Container Tracking API", "description": "REST API for real-time tracking of ocean freight: containers, bills of lading and booking numbers, as well as checking which carriers are supported and how each one can be looked up.\n\nSend a reference number and get back the shipment's current status, the milestones it has already passed, the vessels and ports on its route and the estimated time of arrival, as one JSON response in the same shape whichever carrier is behind it.\n\nAir cargo is a separate product with a document of its own: `air-tracking-api-v1.json`.\n\nFull documentation: https://developer.tracking.one/ocean/container-tracking-api/", "version": "1.0.0" }, "servers": [ { "url": "https://api.tracking.one", "description": "Api Endpoint" } ], "paths": { "/v1/shipments/ocean": { "get": { "tags": ["Container Tracking API v1"], "summary": "Get Ocean Shipment Tracking Information", "description": "Retrieves comprehensive tracking status, route details, transport events, and route coordinates for a specified ocean shipment (container, bill of lading, or booking number).", "operationId": "getOceanShipment", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "referenceNumber", "in": "query", "required": true, "description": "Shipment reference number (container number, bill of lading number, or booking number).", "schema": { "type": "string" }, "example": "MEDU9270627" }, { "name": "referenceType", "in": "query", "required": false, "description": "Optional explicit type of the shipment reference number.", "schema": { "type": "string", "enum": ["CONTAINER", "BL", "BOOKING"] }, "example": "CONTAINER" }, { "name": "carrierCode", "in": "query", "required": false, "description": "Optional ocean carrier code (typically standard SCAC code).", "schema": { "type": "string" }, "example": "MSCU" }, { "name": "routeDetails", "in": "query", "required": false, "description": "Flag to request detailed route segments, coordinates, path points, AIS vessel data (if the container is currently loaded on a vessel), and the last estimated container position within the shipment journey.", "schema": { "type": "boolean", "default": false }, "example": true } ], "responses": { "200": { "description": "Successful shipment tracking response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OceanShipmentResponse" }, "example": { "success": true, "status": "OK", "shipment": { "type": "CONTAINER", "referenceNumber": "UETU7838717", "carrier": { "name": "Maersk", "code": "MAEU" }, "references": { "bookingNumber": null, "blNumber": null, "containerNumber": "UETU7838717" }, "status": "IN_TRANSIT", "updatedAt": "2026-09-01T11:17:37", "cacheExpiresAt": "2026-09-01T23:17:37", "route": { "placeOfReceipt": { "location": { "name": "Savannah", "state": "Georgia", "countryCode": "US", "country": "United States", "unLocode": "USSAV", "timezone": "America/New_York", "coordinates": { "lat": 32.08354, "lng": -81.09983 }, "facility": { "name": "Savannah Garden City Terminal L738", "smdgCode": null, "bicCode": null, "coordinates": null } } }, "portOfLoading": { "location": { "name": "Savannah", "state": "Georgia", "countryCode": "US", "country": "United States", "unLocode": "USSAV", "timezone": "America/New_York", "coordinates": { "lat": 32.08354, "lng": -81.09983 }, "facility": { "name": "Savannah Garden City Terminal L738", "smdgCode": null, "bicCode": null, "coordinates": null } }, "departure": { "date": "2026-08-25T07:17:00", "isActual": true, "transport": { "mode": "VESSEL", "name": "SUAPE EXPRESS", "voyageNumber": "634E", "vesselDetails": { "imo": 9332858, "mmsi": "636093100", "callSign": "5LFL8", "flag": "LR" } } } }, "transshipmentPorts": [ { "location": { "name": "Antwerp", "state": "Flanders", "countryCode": "BE", "country": "Belgium", "unLocode": "BEANR", "timezone": "Europe/Brussels", "coordinates": { "lat": 51.22047, "lng": 4.40026 }, "facility": { "name": "Europa Terminal Quay 869", "smdgCode": null, "bicCode": null, "coordinates": null } }, "arrival": { "date": "2026-09-11T22:00:00", "isActual": false, "transport": { "mode": "VESSEL", "name": "SUAPE EXPRESS", "voyageNumber": "634E", "vesselDetails": { "imo": 9332858, "mmsi": "636093100", "callSign": "5LFL8", "flag": "LR" } } }, "departure": { "date": "2026-09-16T06:00:00", "isActual": false, "transport": { "mode": "VESSEL", "name": "MAERSK SENANG", "voyageNumber": "637W", "vesselDetails": { "imo": 9315240, "mmsi": "565482000", "callSign": "S6CH5", "flag": "SG" } } } }, { "location": { "name": "Bremerhaven", "state": "Bremen", "countryCode": "DE", "country": "Germany", "unLocode": "DEBRV", "timezone": "Europe/Berlin", "coordinates": { "lat": 53.53615, "lng": 8.59298 }, "facility": { "name": "NTB NORTH Sea Terminal Bremerhaven", "smdgCode": null, "bicCode": null, "coordinates": null } }, "arrival": { "date": "2026-09-17T22:00:00", "isActual": false, "transport": { "mode": "VESSEL", "name": "MAERSK SENANG", "voyageNumber": "637W", "vesselDetails": { "imo": 9315240, "mmsi": "565482000", "callSign": "S6CH5", "flag": "SG" } } }, "departure": { "date": "2026-09-23T17:00:00", "isActual": false, "transport": { "mode": "VESSEL", "name": "VENTA MAERSK", "voyageNumber": "639E", "vesselDetails": { "imo": 9775763, "mmsi": "219115000", "callSign": "OWHH2", "flag": "DK" } } } } ], "portOfDischarge": { "location": { "name": "Klaipeda", "state": "Klaipeda County", "countryCode": "LT", "country": "Lithuania", "unLocode": "LTKLJ", "timezone": "Europe/Vilnius", "coordinates": { "lat": 55.7068, "lng": 21.13912 }, "facility": { "name": "Klaipeda port terminal", "smdgCode": null, "bicCode": null, "coordinates": null } }, "arrival": { "date": "2026-09-26T08:00:00", "isActual": false, "transport": { "mode": "VESSEL", "name": "VENTA MAERSK", "voyageNumber": "639E", "vesselDetails": { "imo": 9775763, "mmsi": "219115000", "callSign": "OWHH2", "flag": "DK" } } } }, "placeOfDelivery": { "location": { "name": "Klaipeda", "state": "Klaipeda County", "countryCode": "LT", "country": "Lithuania", "unLocode": "LTKLJ", "timezone": "Europe/Vilnius", "coordinates": { "lat": 55.7068, "lng": 21.13912 }, "facility": { "name": null, "smdgCode": null, "bicCode": null, "coordinates": null } } }, "latestAis": { "transport": { "mode": "VESSEL", "name": "SUAPE EXPRESS", "voyageNumber": null, "vesselDetails": { "imo": 9332858, "mmsi": "636093100", "callSign": "5LFL8", "flag": "LR" } }, "coordinates": { "lat": 41.799793, "lng": -55.141968 }, "timestamp": "2026-09-01T12:31:00", "departure": { "location": { "name": "Norfolk", "state": "Virginia", "countryCode": "US", "country": "United States", "unLocode": "USORF", "timezone": "America/New_York", "coordinates": { "lat": 36.84681, "lng": -76.28522 }, "facility": { "name": null, "smdgCode": null, "bicCode": null, "coordinates": null } }, "date": "2026-08-29T06:51:00", "isActual": true }, "arrival": { "location": { "name": "Southampton", "state": "England", "countryCode": "GB", "country": "United Kingdom", "unLocode": "GBSOU", "timezone": "Europe/London", "coordinates": { "lat": 50.90395, "lng": -1.40428 }, "facility": { "name": null, "smdgCode": null, "bicCode": null, "coordinates": null } }, "date": "2026-09-09T03:00:00", "isActual": false } } }, "containers": [ { "number": "UETU7838717", "size": "40", "type": "High Cube Dry", "isoCode": "45G1", "status": "IN_TRANSIT", "events": [ { "sequenceNumber": 1, "eventType": "EQUIPMENT", "eventTypeCode": "GTOT", "description": "Gate out Empty", "date": "2026-08-20T14:11:00", "isActual": true, "isContainerEmpty": true, "locationRole": "EMPTY_PICKUP", "location": { "name": "Savannah", "state": "Georgia", "countryCode": "US", "country": "United States", "unLocode": "USSAV", "timezone": "America/New_York", "coordinates": { "lat": 32.08354, "lng": -81.09983 }, "facility": { "name": "Savannah Garden City Terminal L738", "smdgCode": null, "bicCode": null, "coordinates": null } }, "transport": null }, { "sequenceNumber": 2, "eventType": "EQUIPMENT", "eventTypeCode": "GTIN", "description": "Gate in", "date": "2026-08-21T13:11:00", "isActual": true, "isContainerEmpty": false, "locationRole": "RECEIPT", "location": { "name": "Savannah", "state": "Georgia", "countryCode": "US", "country": "United States", "unLocode": "USSAV", "timezone": "America/New_York", "coordinates": { "lat": 32.08354, "lng": -81.09983 }, "facility": { "name": "Savannah Garden City Terminal L738", "smdgCode": null, "bicCode": null, "coordinates": null } }, "transport": null }, { "sequenceNumber": 3, "eventType": "EQUIPMENT", "eventTypeCode": "LOAD", "description": "Load", "date": "2026-08-25T01:58:00", "isActual": true, "isContainerEmpty": false, "locationRole": "POL", "location": { "name": "Savannah", "state": "Georgia", "countryCode": "US", "country": "United States", "unLocode": "USSAV", "timezone": "America/New_York", "coordinates": { "lat": 32.08354, "lng": -81.09983 }, "facility": { "name": "Savannah Garden City Terminal L738", "smdgCode": null, "bicCode": null, "coordinates": null } }, "transport": { "mode": "VESSEL", "name": "SUAPE EXPRESS", "voyageNumber": "634E", "vesselDetails": { "imo": 9332858, "mmsi": "636093100", "callSign": "5LFL8", "flag": "LR" } } }, { "sequenceNumber": 4, "eventType": "TRANSPORT", "eventTypeCode": "DEPA", "description": "Vessel departure", "date": "2026-08-25T07:17:00", "isActual": true, "isContainerEmpty": false, "locationRole": "POL", "location": { "name": "Savannah", "state": "Georgia", "countryCode": "US", "country": "United States", "unLocode": "USSAV", "timezone": "America/New_York", "coordinates": { "lat": 32.08354, "lng": -81.09983 }, "facility": { "name": "Savannah Garden City Terminal L738", "smdgCode": null, "bicCode": null, "coordinates": null } }, "transport": { "mode": "VESSEL", "name": "SUAPE EXPRESS", "voyageNumber": "634E", "vesselDetails": { "imo": 9332858, "mmsi": "636093100", "callSign": "5LFL8", "flag": "LR" } } }, { "sequenceNumber": 5, "eventType": "TRANSPORT", "eventTypeCode": "ARRI", "description": "Vessel arrival", "date": "2026-09-11T22:00:00", "isActual": false, "isContainerEmpty": false, "locationRole": "TRANSSHIPMENT", "location": { "name": "Antwerp", "state": "Flanders", "countryCode": "BE", "country": "Belgium", "unLocode": "BEANR", "timezone": "Europe/Brussels", "coordinates": { "lat": 51.22047, "lng": 4.40026 }, "facility": { "name": "Europa Terminal Quay 869", "smdgCode": null, "bicCode": null, "coordinates": null } }, "transport": { "mode": "VESSEL", "name": "SUAPE EXPRESS", "voyageNumber": "634E", "vesselDetails": { "imo": 9332858, "mmsi": "636093100", "callSign": "5LFL8", "flag": "LR" } } }, { "sequenceNumber": 6, "eventType": "TRANSPORT", "eventTypeCode": "DEPA", "description": "Vessel departure", "date": "2026-09-16T06:00:00", "isActual": false, "isContainerEmpty": false, "locationRole": "TRANSSHIPMENT", "location": { "name": "Antwerp", "state": "Flanders", "countryCode": "BE", "country": "Belgium", "unLocode": "BEANR", "timezone": "Europe/Brussels", "coordinates": { "lat": 51.22047, "lng": 4.40026 }, "facility": { "name": "Europa Terminal Quay 869", "smdgCode": null, "bicCode": null, "coordinates": null } }, "transport": { "mode": "VESSEL", "name": "MAERSK SENANG", "voyageNumber": "637W", "vesselDetails": { "imo": 9315240, "mmsi": "565482000", "callSign": "S6CH5", "flag": "SG" } } }, { "sequenceNumber": 7, "eventType": "TRANSPORT", "eventTypeCode": "ARRI", "description": "Vessel arrival", "date": "2026-09-17T22:00:00", "isActual": false, "isContainerEmpty": false, "locationRole": "TRANSSHIPMENT", "location": { "name": "Bremerhaven", "state": "Bremen", "countryCode": "DE", "country": "Germany", "unLocode": "DEBRV", "timezone": "Europe/Berlin", "coordinates": { "lat": 53.53615, "lng": 8.59298 }, "facility": { "name": "NTB NORTH Sea Terminal Bremerhaven", "smdgCode": null, "bicCode": null, "coordinates": null } }, "transport": { "mode": "VESSEL", "name": "MAERSK SENANG", "voyageNumber": "637W", "vesselDetails": { "imo": 9315240, "mmsi": "565482000", "callSign": "S6CH5", "flag": "SG" } } }, { "sequenceNumber": 8, "eventType": "TRANSPORT", "eventTypeCode": "DEPA", "description": "Vessel departure", "date": "2026-09-23T17:00:00", "isActual": false, "isContainerEmpty": false, "locationRole": "TRANSSHIPMENT", "location": { "name": "Bremerhaven", "state": "Bremen", "countryCode": "DE", "country": "Germany", "unLocode": "DEBRV", "timezone": "Europe/Berlin", "coordinates": { "lat": 53.53615, "lng": 8.59298 }, "facility": { "name": "NTB NORTH Sea Terminal Bremerhaven", "smdgCode": null, "bicCode": null, "coordinates": null } }, "transport": { "mode": "VESSEL", "name": "VENTA MAERSK", "voyageNumber": "639E", "vesselDetails": { "imo": 9775763, "mmsi": "219115000", "callSign": "OWHH2", "flag": "DK" } } }, { "sequenceNumber": 9, "eventType": "TRANSPORT", "eventTypeCode": "ARRI", "description": "Vessel arrival", "date": "2026-09-26T08:00:00", "isActual": false, "isContainerEmpty": false, "locationRole": "POD", "location": { "name": "Klaipeda", "state": "Klaipeda County", "countryCode": "LT", "country": "Lithuania", "unLocode": "LTKLJ", "timezone": "Europe/Vilnius", "coordinates": { "lat": 55.7068, "lng": 21.13912 }, "facility": { "name": "Klaipeda port terminal", "smdgCode": null, "bicCode": null, "coordinates": null } }, "transport": { "mode": "VESSEL", "name": "VENTA MAERSK", "voyageNumber": "639E", "vesselDetails": { "imo": 9775763, "mmsi": "219115000", "callSign": "OWHH2", "flag": "DK" } } } ], "routeSegments": [ { "transport": { "mode": "VESSEL", "name": "SUAPE EXPRESS", "voyageNumber": null, "vesselDetails": { "imo": 9332858, "mmsi": "636093100", "callSign": "5LFL8", "flag": "LR" } }, "departure": { "location": { "name": "Savannah", "state": "Georgia", "countryCode": "US", "country": "United States", "unLocode": "USSAV", "timezone": "America/New_York", "coordinates": { "lat": 32.08354, "lng": -81.09983 }, "facility": { "name": null, "smdgCode": null, "bicCode": null, "coordinates": null } } }, "arrival": { "location": { "name": "Antwerp", "state": "Flanders", "countryCode": "BE", "country": "Belgium", "unLocode": "BEANR", "timezone": "Europe/Brussels", "coordinates": { "lat": 51.22047, "lng": 4.40026 }, "facility": { "name": null, "smdgCode": null, "bicCode": null, "coordinates": null } } }, "routePath": [ { "lat": 32.0835, "lng": -81.0998 }, { "lat": 31.7513, "lng": -80.7887 }, { "lat": 31.7417, "lng": -80.7758 }, { "lat": 31.7386, "lng": -80.7614 }, { "lat": 31.7419, "lng": -80.7456 }, { "lat": 41.7998, "lng": -55.142 }, { "lat": 41.87495835346644, "lng": -54.665235619735355 }, { "lat": 50.548, "lng": 0.3519 }, { "lat": 50.5512, "lng": 0.369 }, { "lat": 50.5553, "lng": 0.3859 }, { "lat": 50.5603, "lng": 0.4025 }, { "lat": 50.6763, "lng": 0.7541 }, { "lat": 50.6818, "lng": 0.7699 }, { "lat": 50.6879, "lng": 0.7855 }, { "lat": 50.6944, "lng": 0.801 }, { "lat": 52, "lng": 3.7288 }, { "lat": 52.0034, "lng": 3.7434 }, { "lat": 52.0003, "lng": 3.7563 }, { "lat": 51.9905, "lng": 3.7678 }, { "lat": 51.2205, "lng": 4.4003 } ] }, { "transport": { "mode": "VESSEL", "name": "MAERSK SENANG", "voyageNumber": null, "vesselDetails": { "imo": 9315240, "mmsi": "565482000", "callSign": "S6CH5", "flag": "SG" } }, "departure": { "location": { "name": "Antwerp", "state": "Flanders", "countryCode": "BE", "country": "Belgium", "unLocode": "BEANR", "timezone": "Europe/Brussels", "coordinates": { "lat": 51.22047, "lng": 4.40026 }, "facility": { "name": null, "smdgCode": null, "bicCode": null, "coordinates": null } } }, "arrival": { "location": { "name": "Bremerhaven", "state": "Bremen", "countryCode": "DE", "country": "Germany", "unLocode": "DEBRV", "timezone": "Europe/Berlin", "coordinates": { "lat": 53.53615, "lng": 8.59298 }, "facility": { "name": null, "smdgCode": null, "bicCode": null, "coordinates": null } } }, "routePath": [ { "lat": 51.2205, "lng": 4.4003 }, { "lat": 51.9914, "lng": 3.7671 }, { "lat": 52.0043, "lng": 3.76 }, { "lat": 52.0176, "lng": 3.7592 }, { "lat": 52.0313, "lng": 3.7647 }, { "lat": 53.3383, "lng": 4.5772 }, { "lat": 53.351, "lng": 4.5869 }, { "lat": 53.3614, "lng": 4.5987 }, { "lat": 53.3695, "lng": 4.6124 }, { "lat": 53.5627, "lng": 5.0215 }, { "lat": 53.5705, "lng": 5.0408 }, { "lat": 53.5761, "lng": 5.0607 }, { "lat": 53.5795, "lng": 5.0812 }, { "lat": 53.7037, "lng": 6.1791 }, { "lat": 53.7055, "lng": 6.1957 }, { "lat": 53.7072, "lng": 6.2122 }, { "lat": 53.7088, "lng": 6.2288 }, { "lat": 53.848, "lng": 7.788 }, { "lat": 53.8488, "lng": 7.8028 }, { "lat": 53.8484, "lng": 7.8176 }, { "lat": 53.847, "lng": 7.8323 }, { "lat": 53.8411, "lng": 7.8775 }, { "lat": 53.838, "lng": 7.8918 }, { "lat": 53.8329, "lng": 7.9053 }, { "lat": 53.8256, "lng": 7.9181 }, { "lat": 53.7105, "lng": 8.0894 }, { "lat": 53.7012, "lng": 8.105 }, { "lat": 53.6938, "lng": 8.1215 }, { "lat": 53.6883, "lng": 8.1388 }, { "lat": 53.6462, "lng": 8.3009 }, { "lat": 53.6413, "lng": 8.3185 }, { "lat": 53.6358, "lng": 8.3358 }, { "lat": 53.6297, "lng": 8.3529 }, { "lat": 53.6286, "lng": 8.3559 }, { "lat": 53.6227, "lng": 8.3712 }, { "lat": 53.6166, "lng": 8.3865 }, { "lat": 53.6103, "lng": 8.4016 }, { "lat": 53.5518, "lng": 8.5395 }, { "lat": 53.546, "lng": 8.5547 }, { "lat": 53.5412, "lng": 8.5703 }, { "lat": 53.5375, "lng": 8.5863 }, { "lat": 53.5361, "lng": 8.593 } ] }, { "transport": { "mode": "VESSEL", "name": "VENTA MAERSK", "voyageNumber": null, "vesselDetails": { "imo": 9775763, "mmsi": "219115000", "callSign": "OWHH2", "flag": "DK" } }, "departure": { "location": { "name": "Bremerhaven", "state": "Bremen", "countryCode": "DE", "country": "Germany", "unLocode": "DEBRV", "timezone": "Europe/Berlin", "coordinates": { "lat": 53.53615, "lng": 8.59298 }, "facility": { "name": null, "smdgCode": null, "bicCode": null, "coordinates": null } } }, "arrival": { "location": { "name": "Klaipeda", "state": "Klaipeda County", "countryCode": "LT", "country": "Lithuania", "unLocode": "LTKLJ", "timezone": "Europe/Vilnius", "coordinates": { "lat": 55.7068, "lng": 21.13912 }, "facility": { "name": null, "smdgCode": null, "bicCode": null, "coordinates": null } } }, "routePath": [ { "lat": 53.5361, "lng": 8.593 }, { "lat": 53.5363, "lng": 8.5924 }, { "lat": 53.5423, "lng": 8.5729 }, { "lat": 53.552, "lng": 8.5555 }, { "lat": 53.5654, "lng": 8.5402 }, { "lat": 53.5723, "lng": 8.5337 }, { "lat": 53.5842, "lng": 8.5226 }, { "lat": 53.5962, "lng": 8.5115 }, { "lat": 53.6081, "lng": 8.5004 }, { "lat": 53.6085, "lng": 8.5 }, { "lat": 53.6211, "lng": 8.4899 }, { "lat": 53.6347, "lng": 8.4813 }, { "lat": 53.6493, "lng": 8.4745 }, { "lat": 53.6529, "lng": 8.4731 }, { "lat": 53.6702, "lng": 8.468 }, { "lat": 53.6879, "lng": 8.4664 }, { "lat": 53.7059, "lng": 8.4681 }, { "lat": 53.6863, "lng": 8.4644 }, { "lat": 53.7015, "lng": 8.4677 }, { "lat": 53.7164, "lng": 8.472 }, { "lat": 53.731, "lng": 8.4772 }, { "lat": 53.8633, "lng": 8.5287 }, { "lat": 53.8762, "lng": 8.5359 }, { "lat": 53.8861, "lng": 8.546 }, { "lat": 53.8931, "lng": 8.5591 }, { "lat": 53.9006, "lng": 8.579 }, { "lat": 53.9053, "lng": 8.5945 }, { "lat": 53.908, "lng": 8.6103 }, { "lat": 53.9086, "lng": 8.6264 }, { "lat": 53.9075, "lng": 8.6763 }, { "lat": 53.9069, "lng": 8.6926 }, { "lat": 53.906, "lng": 8.7088 }, { "lat": 53.9046, "lng": 8.7251 }, { "lat": 53.8802, "lng": 8.9783 }, { "lat": 53.8789, "lng": 8.9986 }, { "lat": 53.8789, "lng": 9.019 }, { "lat": 53.8801, "lng": 9.0393 }, { "lat": 53.8869, "lng": 9.1121 }, { "lat": 53.889, "lng": 9.1251 }, { "lat": 53.8931, "lng": 9.1374 }, { "lat": 53.8989, "lng": 9.1491 }, { "lat": 53.9603, "lng": 9.2537 }, { "lat": 53.968, "lng": 9.264 }, { "lat": 53.9775, "lng": 9.2722 }, { "lat": 53.9889, "lng": 9.2783 }, { "lat": 54.1245, "lng": 9.3331 }, { "lat": 54.1372, "lng": 9.3405 }, { "lat": 54.1466, "lng": 9.351 }, { "lat": 54.1525, "lng": 9.3646 }, { "lat": 54.2058, "lng": 9.5543 }, { "lat": 54.2116, "lng": 9.5693 }, { "lat": 54.2197, "lng": 9.5828 }, { "lat": 54.2304, "lng": 9.5949 }, { "lat": 54.2674, "lng": 9.6303 }, { "lat": 54.2774, "lng": 9.6418 }, { "lat": 54.285, "lng": 9.6549 }, { "lat": 54.29, "lng": 9.6693 }, { "lat": 54.2901, "lng": 9.6698 }, { "lat": 54.295, "lng": 9.6844 }, { "lat": 54.3019, "lng": 9.698 }, { "lat": 54.3109, "lng": 9.7105 }, { "lat": 54.327, "lng": 9.7299 }, { "lat": 54.3361, "lng": 9.7415 }, { "lat": 54.3443, "lng": 9.7535 }, { "lat": 54.3519, "lng": 9.7661 }, { "lat": 54.3521, "lng": 9.7665 }, { "lat": 54.3581, "lng": 9.7796 }, { "lat": 54.3618, "lng": 9.7934 }, { "lat": 54.3633, "lng": 9.8078 }, { "lat": 54.3637, "lng": 9.8222 }, { "lat": 54.363, "lng": 9.8457 }, { "lat": 54.3598, "lng": 9.8689 }, { "lat": 54.3539, "lng": 9.8916 }, { "lat": 54.3516, "lng": 9.8991 }, { "lat": 54.3466, "lng": 9.9178 }, { "lat": 54.3434, "lng": 9.9368 }, { "lat": 54.342, "lng": 9.9561 }, { "lat": 54.3429, "lng": 9.9272 }, { "lat": 54.3429, "lng": 9.9466 }, { "lat": 54.3441, "lng": 9.9659 }, { "lat": 54.3466, "lng": 9.9852 }, { "lat": 54.3424, "lng": 9.9589 }, { "lat": 54.3465, "lng": 9.9785 }, { "lat": 54.3522, "lng": 9.9975 }, { "lat": 54.3597, "lng": 10.0161 }, { "lat": 54.3506, "lng": 9.9961 }, { "lat": 54.3558, "lng": 10.0098 }, { "lat": 54.3592, "lng": 10.0239 }, { "lat": 54.3609, "lng": 10.0385 }, { "lat": 54.361, "lng": 10.0394 }, { "lat": 54.3625, "lng": 10.0538 }, { "lat": 54.3652, "lng": 10.0679 }, { "lat": 54.3693, "lng": 10.0817 }, { "lat": 54.3678, "lng": 10.0775 }, { "lat": 54.3687, "lng": 10.0804 }, { "lat": 54.3695, "lng": 10.0833 }, { "lat": 54.3702, "lng": 10.0862 }, { "lat": 54.3693, "lng": 10.0818 }, { "lat": 54.3698, "lng": 10.0848 }, { "lat": 54.3702, "lng": 10.0878 }, { "lat": 54.3705, "lng": 10.0908 }, { "lat": 54.3702, "lng": 10.0866 }, { "lat": 54.3706, "lng": 10.1002 }, { "lat": 54.37, "lng": 10.1138 }, { "lat": 54.3682, "lng": 10.1273 }, { "lat": 54.3659, "lng": 10.1406 }, { "lat": 54.3654, "lng": 10.1535 }, { "lat": 54.3684, "lng": 10.1656 }, { "lat": 54.3747, "lng": 10.1769 }, { "lat": 54.3749, "lng": 10.1772 }, { "lat": 54.3835, "lng": 10.1877 }, { "lat": 54.3928, "lng": 10.1973 }, { "lat": 54.403, "lng": 10.2061 }, { "lat": 54.4051, "lng": 10.2079 }, { "lat": 54.4163, "lng": 10.2178 }, { "lat": 54.4263, "lng": 10.2288 }, { "lat": 54.4352, "lng": 10.2409 }, { "lat": 54.4301, "lng": 10.2331 }, { "lat": 54.4377, "lng": 10.2464 }, { "lat": 54.4438, "lng": 10.2603 }, { "lat": 54.4484, "lng": 10.2749 }, { "lat": 54.4489, "lng": 10.2768 }, { "lat": 54.4521, "lng": 10.2908 }, { "lat": 54.4547, "lng": 10.3049 }, { "lat": 54.4567, "lng": 10.3191 }, { "lat": 54.4568, "lng": 10.3199 }, { "lat": 54.458, "lng": 10.3339 }, { "lat": 54.4583, "lng": 10.3479 }, { "lat": 54.4577, "lng": 10.362 }, { "lat": 54.413, "lng": 11.0014 }, { "lat": 54.412, "lng": 11.0148 }, { "lat": 54.411, "lng": 11.0283 }, { "lat": 54.4099, "lng": 11.0418 }, { "lat": 54.4001, "lng": 11.1648 }, { "lat": 54.399, "lng": 11.1782 }, { "lat": 54.3982, "lng": 11.1917 }, { "lat": 54.3974, "lng": 11.2052 }, { "lat": 54.3953, "lng": 11.2501 }, { "lat": 54.395, "lng": 11.2643 }, { "lat": 54.3954, "lng": 11.2786 }, { "lat": 54.3966, "lng": 11.2928 }, { "lat": 54.449, "lng": 11.7702 }, { "lat": 54.4511, "lng": 11.7868 }, { "lat": 54.4539, "lng": 11.8034 }, { "lat": 54.4574, "lng": 11.8198 }, { "lat": 54.8148, "lng": 13.356 }, { "lat": 54.8179, "lng": 13.3724 }, { "lat": 54.8196, "lng": 13.3889 }, { "lat": 54.8199, "lng": 13.4057 }, { "lat": 54.7842, "lng": 15.058 }, { "lat": 54.7844, "lng": 15.0729 }, { "lat": 54.7854, "lng": 15.0877 }, { "lat": 54.7875, "lng": 15.1024 }, { "lat": 55.7515, "lng": 20.7518 }, { "lat": 55.7532, "lng": 20.7665 }, { "lat": 55.7534, "lng": 20.7812 }, { "lat": 55.7522, "lng": 20.796 }, { "lat": 55.7068, "lng": 21.1391 } ] } ], "lastPosition": { "lat": 41.87495835346644, "lng": -54.665235619735355 } } ] } } } } }, "401": { "description": "Unauthorized - Missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OceanErrorResponse" } } } } } } }, "/v1/carriers/ocean": { "get": { "tags": ["Container Tracking API v1"], "summary": "Get Supported Ocean Carriers", "description": "Retrieves the list of supported ocean carriers along with their capabilities, operational statuses, and supported tracking query types. Authorization is not required.", "operationId": "getOceanCarriers", "security": [], "responses": { "200": { "description": "List of ocean carriers retrieved successfully.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OceanCarrierInfo" } }, "example": [ { "name": "Mediterranean Shipping Company (MSC)", "carrierCode": "MSCU", "isMaintenance": false, "supportsContainer": true, "supportsBl": true, "supportsBooking": true, "supportsBlContainer": false, "supportsBookingContainer": false }, { "name": "Maersk", "carrierCode": "MAEU", "isMaintenance": false, "supportsContainer": true, "supportsBl": true, "supportsBooking": true, "supportsBlContainer": false, "supportsBookingContainer": false } ] } } } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "opaque", "description": "HTTP Bearer token authorization header." } }, "schemas": { "OceanErrorResponse": { "type": "object", "description": "Standard API error response wrapper.", "properties": { "message": { "type": "string", "description": "Detailed human-readable error description.", "example": "Invalid or expired Bearer token provided." } }, "required": ["message"] }, "OceanCarrierInfo": { "type": "object", "description": "Information and tracking capabilities of an ocean carrier.", "properties": { "name": { "type": "string", "description": "Full official name of the ocean shipping line.", "example": "Mediterranean Shipping Company (MSC)" }, "carrierCode": { "type": "string", "description": "Standard carrier identifier or SCAC code.", "example": "MSCU" }, "isMaintenance": { "type": "boolean", "description": "Indicates whether tracking service for this carrier is undergoing maintenance.", "example": false }, "supportsContainer": { "type": "boolean", "description": "Indicates whether container number tracking is supported.", "example": true }, "supportsBl": { "type": "boolean", "description": "Indicates whether Bill of Lading (B/L) tracking is supported.", "example": true }, "supportsBooking": { "type": "boolean", "description": "Indicates whether booking number tracking is supported.", "example": true }, "supportsBlContainer": { "type": "boolean", "description": "Indicates whether container number is mandatory when querying by B/L.", "example": false }, "supportsBookingContainer": { "type": "boolean", "description": "Indicates whether container number is mandatory when querying by booking number.", "example": false } }, "required": [ "name", "carrierCode", "isMaintenance", "supportsContainer", "supportsBl", "supportsBooking", "supportsBlContainer", "supportsBookingContainer" ] }, "OceanCoordinates": { "type": "object", "description": "Geographic location coordinates in decimal degrees.", "properties": { "lat": { "type": "number", "format": "double", "description": "Latitude angle in decimal degrees.", "example": -33.92584 }, "lng": { "type": "number", "format": "double", "description": "Longitude angle in decimal degrees.", "example": 18.42322 } }, "required": ["lat", "lng"] }, "OceanFacility": { "type": "object", "description": "Terminal or facility details.", "nullable": true, "properties": { "name": { "type": "string", "nullable": true, "description": "Official name of the terminal or depot facility.", "example": "TRANSNET PORT TERMINALS CAPE TOWN" }, "smdgCode": { "type": "string", "nullable": true, "description": "SMDG terminal code.", "example": "TNCT" }, "bicCode": { "type": "string", "nullable": true, "description": "BIC facility code.", "example": "ZACPTGKKF" }, "coordinates": { "$ref": "#/components/schemas/OceanCoordinates" } } }, "OceanLocation": { "type": "object", "description": "Geographic location and facility breakdown.", "properties": { "name": { "type": "string", "description": "City or port geographical name.", "example": "Cape Town" }, "state": { "type": "string", "nullable": true, "description": "State, province, or district name.", "example": "Western Cape" }, "countryCode": { "type": "string", "description": "ISO 3166-1 alpha-2 two-letter country code.", "example": "ZA" }, "country": { "type": "string", "description": "Full country name.", "example": "South Africa" }, "unLocode": { "type": "string", "nullable": true, "description": "United Nations Code for Trade and Transport Locations (UN/LOCODE).", "example": "ZACPT" }, "timezone": { "type": "string", "description": "IANA time zone identifier.", "example": "Africa/Johannesburg" }, "coordinates": { "$ref": "#/components/schemas/OceanCoordinates" }, "facility": { "$ref": "#/components/schemas/OceanFacility" } }, "required": ["name", "countryCode", "country", "timezone"] }, "OceanVesselDetails": { "type": "object", "description": "Technical maritime parameters of the vessel.", "nullable": true, "properties": { "imo": { "type": "integer", "nullable": true, "description": "International Maritime Organization (IMO) number.", "example": 9778090 }, "mmsi": { "type": "string", "nullable": true, "description": "Maritime Mobile Service Identity (MMSI) 9-digit number.", "example": "255806032" }, "callSign": { "type": "string", "nullable": true, "description": "Radio call sign assigned to the vessel.", "example": "CQIP7" }, "flag": { "type": "string", "nullable": true, "description": "ISO country code of the vessel registry flag.", "example": "PT" } } }, "OceanTransport": { "type": "object", "description": "Transport conveyance details.", "nullable": true, "properties": { "mode": { "type": "string", "nullable": true, "enum": ["VESSEL", "TRUCK", "RAIL", "AIR", "BARGE"], "description": "Mode of transportation. Possible values:\n* `VESSEL` - Ocean or feeder vessel transport\n* `TRUCK` - Road transport (truck)\n* `RAIL` - Rail transport\n* `AIR` - Air transport\n* `BARGE` - Inland waterway barge transport", "example": "VESSEL" }, "name": { "type": "string", "nullable": true, "description": "Name of the vessel or transport conveyance.", "example": "MSC YASHI B" }, "voyageNumber": { "type": "string", "nullable": true, "description": "Carrier voyage or trip identifier.", "example": "NZ626R" }, "vesselDetails": { "$ref": "#/components/schemas/OceanVesselDetails" } }, "required": ["mode"] }, "OceanLatestAis": { "type": "object", "description": "Real-time AIS (Automatic Identification System) vessel telemetry data. Returned only when `routeDetails=true` and the shipment or its container(s) are currently loaded on an active ocean vessel.", "nullable": true, "properties": { "transport": { "$ref": "#/components/schemas/OceanTransport" }, "coordinates": { "$ref": "#/components/schemas/OceanCoordinates" }, "timestamp": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp of the last received AIS position signal in UTC (ISO 8601 format without timezone offset, e.g. YYYY-MM-DDThh:mm:ss).", "example": "2026-09-01T13:45:00" }, "departure": { "type": "object", "description": "Current vessel voyage departure leg details.", "nullable": true, "properties": { "location": { "$ref": "#/components/schemas/OceanLocation" }, "date": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp of vessel departure in UTC (ISO 8601 format without timezone offset, e.g. YYYY-MM-DDThh:mm:ss).", "example": "2026-08-31T23:21:00" }, "isActual": { "type": "boolean", "nullable": true, "description": "Indicates whether the departure timestamp is actual (`true`) or estimated/scheduled (`false`).", "example": true } } }, "arrival": { "type": "object", "description": "Current vessel voyage next arrival leg details.", "nullable": true, "properties": { "location": { "$ref": "#/components/schemas/OceanLocation" }, "date": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp of expected vessel arrival in UTC (ISO 8601 format without timezone offset, e.g. YYYY-MM-DDThh:mm:ss).", "example": "2026-09-03T08:00:00" }, "isActual": { "type": "boolean", "nullable": true, "description": "Indicates whether the arrival timestamp is actual (`true`) or estimated/scheduled (`false`).", "example": false } } } } }, "OceanLegDeparture": { "type": "object", "description": "Leg departure timestamp and vehicle details.", "nullable": true, "properties": { "date": { "type": "string", "format": "date-time", "nullable": true, "description": "Scheduled, estimated, or actual departure timestamp.", "example": "2026-07-06T00:00:00" }, "isActual": { "type": "boolean", "nullable": true, "description": "Flag indicating whether departure date is actual (true) or estimated/scheduled (false).", "example": true }, "transport": { "$ref": "#/components/schemas/OceanTransport" } } }, "OceanLegArrival": { "type": "object", "description": "Leg arrival timestamp and vehicle details.", "nullable": true, "properties": { "date": { "type": "string", "format": "date-time", "nullable": true, "description": "Scheduled, estimated, or actual arrival timestamp.", "example": "2026-07-29T00:00:00" }, "isActual": { "type": "boolean", "nullable": true, "description": "Flag indicating whether arrival date is actual (true) or estimated/scheduled (false).", "example": true }, "transport": { "$ref": "#/components/schemas/OceanTransport" } } }, "OceanRouteLocationPoint": { "type": "object", "description": "Simple route node containing location information only (without departure or arrival transport legs).", "nullable": true, "properties": { "location": { "$ref": "#/components/schemas/OceanLocation" } }, "required": ["location"] }, "OceanRouteDeparturePoint": { "type": "object", "description": "Route node containing location and departure transport leg details only (e.g. Port of Loading).", "nullable": true, "properties": { "location": { "$ref": "#/components/schemas/OceanLocation" }, "departure": { "$ref": "#/components/schemas/OceanLegDeparture" } } }, "OceanRouteArrivalPoint": { "type": "object", "description": "Route node containing location and arrival transport leg details only (e.g. Port of Discharge).", "nullable": true, "properties": { "location": { "$ref": "#/components/schemas/OceanLocation" }, "arrival": { "$ref": "#/components/schemas/OceanLegArrival" } } }, "OceanTransshipmentPort": { "type": "object", "description": "Intermediate transshipment port entry.", "properties": { "location": { "$ref": "#/components/schemas/OceanLocation" }, "arrival": { "$ref": "#/components/schemas/OceanLegArrival" }, "departure": { "$ref": "#/components/schemas/OceanLegDeparture" } } }, "OceanRoute": { "type": "object", "description": "Shipment itinerary milestones overview.", "properties": { "placeOfReceipt": { "$ref": "#/components/schemas/OceanRouteLocationPoint" }, "portOfLoading": { "$ref": "#/components/schemas/OceanRouteDeparturePoint" }, "transshipmentPorts": { "type": "array", "description": "List of intermediate transshipment hubs.", "items": { "$ref": "#/components/schemas/OceanTransshipmentPort" } }, "portOfDischarge": { "$ref": "#/components/schemas/OceanRouteArrivalPoint" }, "placeOfDelivery": { "$ref": "#/components/schemas/OceanRouteLocationPoint" }, "latestAis": { "$ref": "#/components/schemas/OceanLatestAis" } } }, "OceanContainerEvent": { "type": "object", "description": "Single milestone movement event in container life-cycle.", "properties": { "sequenceNumber": { "type": "integer", "description": "Sequential order number of the event.", "example": 1 }, "eventType": { "type": "string", "nullable": true, "enum": ["SHIPMENT", "TRANSPORT", "EQUIPMENT"], "description": "Broad classification of event according to DCSA standards. Possible values:\n* `SHIPMENT` - Events related to the commercial or documentary status of a shipment (e.g., Booking, Bill of Lading milestones)\n* `TRANSPORT` - Events related to transport conveyance movements (e.g., vessel arrivals, departures, or progress updates)\n* `EQUIPMENT` - Events related to the container unit operational lifecycle (e.g., Gate In, Gate Out, Load, Discharge, Empty Pickup/Return)", "example": "EQUIPMENT" }, "eventTypeCode": { "type": "string", "nullable": true, "enum": [ "LOAD", "DISC", "GTIN", "GTOT", "STUF", "STRP", "PICK", "DROP", "INSP", "RSEA", "RMVD", "AVPU", "AVDO", "CUSS", "CUSI", "CUSR", "CROS", "ARRI", "DEPA", "RECE", "DRFT", "PENA", "PENU", "PENC", "CONF", "REJE", "APPR", "ISSU", "SURR", "SUBM", "VOID", "REQS", "CMPL", "HOLD", "RELS", "CANC" ], "description": "Standardized event status code compliant with DCSA (Digital Container Shipping Association) specifications, categorized by `eventType`:\n\n**EQUIPMENT Events:**\n* `LOAD` - Loaded onto a transport conveyance\n* `DISC` - Discharged from a transport conveyance\n* `GTIN` - Gate-In to a facility\n* `GTOT` - Gate-Out from a facility\n* `STUF` - Stuffed (Cargo loaded into container)\n* `STRP` - Stripped (Cargo unloaded from container)\n* `PICK` - Picked up\n* `DROP` - Dropped off\n* `INSP` - Inspected\n* `RSEA` - Resealed\n* `RMVD` - Equipment removed\n* `AVPU` - Available for Pick-up\n* `AVDO` - Available for Delivery/Drop-off\n* `CUSS` - Selected for Customs Inspection\n* `CUSI` - Customs Inspection underway\n* `CUSR` - Customs Released\n* `CROS` - Cross-docked\n\n**TRANSPORT Events:**\n* `ARRI` - Transport conveyance Arrival\n* `DEPA` - Transport conveyance Departure\n\n**SHIPMENT Events:**\n* `RECE` - Received\n* `DRFT` - Draft\n* `PENA` - Pending Approval\n* `PENU` - Pending Update\n* `PENC` - Pending Cancellation\n* `CONF` - Confirmed\n* `REJE` - Rejected\n* `APPR` - Approved\n* `ISSU` - Issued\n* `SURR` - Surrendered\n* `SUBM` - Submitted\n* `VOID` - Voided\n* `REQS` - Requested\n* `CMPL` - Completed\n* `HOLD` - Shipment on Hold\n* `RELS` - Shipment Released\n* `CANC` - Cancelled", "example": "GTOT" }, "description": { "type": "string", "description": "Human-readable description of the milestone.", "example": "Empty to Shipper" }, "date": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp of the event occurrence in local time at the event location (ISO 8601 format without UTC offset, e.g. YYYY-MM-DDThh:mm:ss). The applicable time zone is defined in the associated `location.timezone` field.", "example": "2026-07-01T00:00:00" }, "isActual": { "type": "boolean", "description": "Flag indicating if the timestamp is actual or estimated.", "example": true }, "isContainerEmpty": { "type": "boolean", "description": "Flag indicating if the container was empty or full at event time.", "example": true }, "locationRole": { "type": "string", "nullable": true, "enum": [ "EMPTY_PICKUP", "STUFFING", "RECEIPT", "POL", "TRANSSHIPMENT", "POD", "WAYPOINT", "CUSTOMS", "INCIDENT", "DELIVERY", "STRIPPING", "EMPTY_RETURN" ], "description": "Operational role of the event location within the shipment journey. Possible values:\n\n**Pre-carriage & Preparation:**\n* `EMPTY_PICKUP` - Empty container release depot\n* `STUFFING` - Cargo stuffing warehouse\n* `RECEIPT` - Place of Receipt (cargo acceptance point by carrier)\n\n**Main Ocean Carriage:**\n* `POL` - Port of Loading\n* `TRANSSHIPMENT` - Transshipment Port (T/S Port)\n* `POD` - Port of Discharge\n\n**Intermodal & Transit Points:**\n* `WAYPOINT` - Intermediate transit hub (rail ramp, inland terminal, truck hub)\n\n**Special & Customs Locations:**\n* `CUSTOMS` - Customs inspection zone or bonded warehouse\n* `INCIDENT` - Location where an incident occurred (accident, damage, loss)\n\n**On-carriage & Completion:**\n* `DELIVERY` - Place of Delivery (final destination)\n* `STRIPPING` - Cargo stripping/devanning warehouse\n* `EMPTY_RETURN` - Empty container return depot", "example": "EMPTY_PICKUP" }, "location": { "$ref": "#/components/schemas/OceanLocation" }, "transport": { "$ref": "#/components/schemas/OceanTransport" } }, "required": [ "sequenceNumber", "eventType", "eventTypeCode", "description", "date", "isActual", "isContainerEmpty", "locationRole" ] }, "OceanContainer": { "type": "object", "description": "Container equipment details and chronological history.", "properties": { "number": { "type": "string", "description": "Container ISO identification prefix and serial number.", "example": "MEDU9270627" }, "size": { "type": "string", "description": "Nominal container size in feet.", "example": "40" }, "type": { "type": "string", "description": "Descriptive container type name.", "example": "High Cube Reefer" }, "isoCode": { "type": "string", "description": "ISO 6346 equipment size and type code.", "example": "45R1" }, "status": { "type": "string", "nullable": true, "enum": [ "PLANNED", "IN_TRANSIT", "DELIVERED", "CANCELLED" ], "description": "Current operational status of the container unit. Possible values:\n* `PLANNED` - Container movement is planned or booked, but transport has not yet commenced\n* `IN_TRANSIT` - Container is actively in transit (on vessel, rail, or road)\n* `DELIVERED` - Container has reached its destination and been delivered\n* `CANCELLED` - Container movement or booking has been cancelled", "example": "DELIVERED" }, "events": { "type": "array", "description": "Chronological history of movement events.", "items": { "$ref": "#/components/schemas/OceanContainerEvent" } }, "routeSegments": { "type": "array", "description": "Detailed path segments with geographic trajectory points (included if routeDetails=true).", "items": { "$ref": "#/components/schemas/OceanRouteSegment" } }, "lastPosition": { "$ref": "#/components/schemas/OceanCoordinates" } }, "required": [ "number", "size", "type", "isoCode", "status", "events" ] }, "OceanRouteSegment": { "type": "object", "description": "Path segment containing departure, arrival, transport mode, and GIS trajectory points.", "properties": { "transport": { "$ref": "#/components/schemas/OceanTransport" }, "departure": { "type": "object", "description": "Segment departure point.", "properties": { "location": { "$ref": "#/components/schemas/OceanLocation" } } }, "arrival": { "type": "object", "description": "Segment arrival point.", "properties": { "location": { "$ref": "#/components/schemas/OceanLocation" } } }, "routePath": { "type": "array", "description": "Array of coordinate waypoints forming the segment map trajectory.", "items": { "$ref": "#/components/schemas/OceanCoordinates" } } } }, "OceanCarrierRef": { "type": "object", "description": "Carrier information referenced in shipment payload.", "properties": { "name": { "type": "string", "description": "Carrier name.", "example": "Mediterranean Shipping Company (MSC)" }, "code": { "type": "string", "description": "Carrier code or SCAC.", "example": "MSCU" } }, "required": ["name", "code"] }, "OceanReferences": { "type": "object", "description": "Cross-referenced booking, BL, and container numbers.", "properties": { "bookingNumber": { "type": "string", "nullable": true, "description": "Associated booking reference number.", "example": null }, "blNumber": { "type": "string", "nullable": true, "description": "Associated Bill of Lading reference number.", "example": null }, "containerNumber": { "type": "string", "nullable": true, "description": "Associated container unit reference number.", "example": "MEDU9270627" } } }, "OceanShipment": { "type": "object", "description": "Shipment master entity containing route, containers, and tracking metadata.", "properties": { "type": { "type": "string", "nullable": true, "enum": ["CONTAINER", "BL", "BOOKING"], "description": "Type of requested tracking reference number. Possible values:\n* `CONTAINER` - Shipping container unit number (e.g., ISO container code)\n* `BL` - Bill of Lading (B/L) reference number\n* `BOOKING` - Ocean carrier booking reservation number", "example": "CONTAINER" }, "referenceNumber": { "type": "string", "description": "The queried reference string.", "example": "MEDU9270627" }, "carrier": { "$ref": "#/components/schemas/OceanCarrierRef" }, "references": { "$ref": "#/components/schemas/OceanReferences" }, "status": { "type": "string", "nullable": true, "enum": [ "PLANNED", "IN_TRANSIT", "DELIVERED", "CANCELLED" ], "description": "Overall current status of the shipment. Possible values:\n* `PLANNED` - Shipment is booked or scheduled, but transport has not yet commenced\n* `IN_TRANSIT` - Cargo is actively in transit (on water, rail, or road)\n* `DELIVERED` - Cargo has reached its final destination and been delivered\n* `CANCELLED` - Shipment booking or operation has been cancelled", "example": "DELIVERED" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when shipment tracking status was last updated (in UTC, ISO 8601 format).", "example": "2026-08-21T12:27:40" }, "cacheExpiresAt": { "type": "string", "format": "date-time", "description": "Timestamp when the cached tracking response expires (in UTC, ISO 8601 format). Once this timestamp passes, a new API request can be made to retrieve fresh tracking data, provided the shipment is not yet completed.", "example": "2026-08-21T12:27:40" }, "route": { "$ref": "#/components/schemas/OceanRoute" }, "containers": { "type": "array", "description": "Array of equipment units attached to shipment.", "items": { "$ref": "#/components/schemas/OceanContainer" } } }, "required": [ "type", "referenceNumber", "carrier", "references", "status", "updatedAt" ] }, "OceanShipmentResponse": { "type": "object", "description": "Top-level API envelope response for ocean shipment tracking.", "properties": { "success": { "type": "boolean", "description": "Boolean flag indicating success status.", "example": true }, "status": { "type": "string", "nullable": true, "enum": [ "OK", "MISSING_REQUIRED_PARAMETER", "INVALID_CARRIER_CODE", "INVALID_REFERENCE_TYPE", "INVALID_REFERENCE_NUMBER", "CARRIER_AUTO_DETECT_FAILED", "REFERENCE_TYPE_AUTO_DETECT_FAILED", "CARRIER_NOT_SUPPORTED", "UNSUPPORTED_REFERENCE_TYPE", "CARRIER_UNDER_MAINTENANCE", "CARRIER_NO_RESPONSE", "SHIPMENT_NOT_FOUND", "SHIPMENT_CANCELLED", "INTERNAL_SERVER_ERROR" ], "description": "Application response or status code. Possible values:\n\n**Success:**\n* `OK` - Request processed successfully\n\n**Validation & Auto-detection:**\n* `MISSING_REQUIRED_PARAMETER` - Required query parameter is missing\n* `INVALID_CARRIER_CODE` - Provided carrier code is invalid or unknown\n* `INVALID_REFERENCE_TYPE` - Provided reference type is invalid\n* `INVALID_REFERENCE_NUMBER` - Provided reference number format is invalid\n* `CARRIER_AUTO_DETECT_FAILED` - Failed to auto-detect carrier from reference number\n* `REFERENCE_TYPE_AUTO_DETECT_FAILED` - Failed to auto-detect reference type\n\n**Carrier Support & Availability:**\n* `CARRIER_NOT_SUPPORTED` - The specified carrier is not supported\n* `UNSUPPORTED_REFERENCE_TYPE` - Carrier does not support tracking by this reference type\n* `CARRIER_UNDER_MAINTENANCE` - Carrier integration is temporarily under maintenance\n* `CARRIER_NO_RESPONSE` - Carrier system timed out or failed to respond\n\n**Shipment Errors:**\n* `SHIPMENT_NOT_FOUND` - Shipment with the given reference was not found\n* `SHIPMENT_CANCELLED` - Shipment has been cancelled by the carrier\n\n**System Errors:**\n* `INTERNAL_SERVER_ERROR` - Unexpected internal server error", "example": "OK" }, "shipment": { "$ref": "#/components/schemas/OceanShipment" } }, "required": ["success", "status", "shipment"] } } } }