GoComet
Migrate from GoComet to TimeToCargo API v2: authentication, requests and response handling
This guide covers migration from GoComet Integration API v1 to TimeToCargo API v2. GoComet returns a permanent tracking_id when tracking starts. A TimeToCargo batch request returns a temporary task_id, with the permanent ID available in the task result.
See the migration workflow for importing references and setting up notifications. Full TimeToCargo schemas are in the API reference.
Authentication
GoComet uses email/password token generation followed by a token field. The GoComet base URL is https://tracking.gocomet.com.
To switch to TimeToCargo:
- Create a key in your TimeToCargo account.
- Change the base URL to
https://tracking.timetocargo.com/v2. For example, the full tracking endpoint ishttps://tracking.timetocargo.com/v2/tracking. - Send the new key in the
api_keyquery parameter of every request, including batch tasks and webhook management. Keys and tokens from the former provider cannot be reused.
See authentication for key usage and request limits.
Tracking records and identifiers
| GoComet | TimeToCargo | Required change |
|---|---|---|
tracking / tracking_id | shipment / id | Map the GoComet tracking_id to the new tracking ID. Use the new ID to edit labels and stop tracking. |
tracking_number + tracking_type | track_number.value + type | Copy the reference and convert its type using the request table below. The internal tracking_id is not a carrier reference. |
updated_trackings | data.data | Retrieve current records from data.data[]. To retain change history, configure webhooks and store notifications in your system. |
Operation mapping
| GoComet | TimeToCargo | Required change |
|---|---|---|
POST /api/v1/integrations/add_tracking_number | POST /v2/tracking/batch → GET /v2/tracking/batch | Submit one entry in tracked_items. Retrieve the task result and save the permanent ID from data.results[].data.tracking_metadata.id. |
POST /api/v1/integrations/add-multiple-tracking | POST /v2/tracking/batch → GET /v2/tracking/batch | Split references into groups of at most 500. Retrieve each task's results and check every item's success. |
GET /api/v1/integrations/live-tracking | GET /v2/shipments | Fetch current records using page and limit. This request has no filters for source IDs, references or update periods. |
GET /api/v1/integrations/trackings-by-reference | GET /v2/shipments + your ID mapping | Store a mapping from your order reference to the new ID. Fetch list pages and select the record with that ID. |
POST /api/v1/integrations/update-multiple-tracking, add-or-update-multiple-tracking | Partial equivalent | To edit a label, use PATCH /v2/shipments/{id} with note. Start a new tracking request for a different reference. There is no operation that updates all fields. |
DELETE /api/v1/integrations/delete-trackings | DELETE /v2/shipments | Pass new IDs in the shipmentIds array. See the lifecycle guide for archiving and deletion rules. |
PUT /api/v1/integrations/restore-trackings | No direct equivalent | Check reactivation rules in the lifecycle guide. Reactivation uses a new tracking request rather than a restore operation. |
GET /api/v1/integrations/mapdata | GET /v2/shipments?need_route=true | Read the selected record's route from tracked_item.data.data.route_info. Update the map handler to use its point arrays. |
Request parameters
| GoComet | TimeToCargo | Required change |
|---|---|---|
tracking.tracking_number | tracked_items[].track_number.value | Pass the reference in tracked_items[].track_number.value in the batch request body. |
tracking.tracking_type | tracked_items[].track_number.type | Replace cn with container, keep bl, and replace bn with bk. This API does not support pro, po or ln. |
tracking.mode | No separate parameter | Omit mode. This guide covers ocean shipments, identified by ocean in GoComet. |
tracking.carrier_code | tracked_items[].company | Map the GoComet code to a SCAC from GET /v2/companies and pass that SCAC in company. |
tracking.reference_no / remarks / other_data | note + your own store | Save one label of up to 40 characters as note through PATCH /v2/shipments/{id}. Keep other metadata in your system. |
start_date / end_date / tracking_ids[] | page / limit / status | Remove these filters from the request. Fetch current records page by page and select IDs locally. Retain period-based history separately. |
Response fields
Select a record from data.data[] in the GET /v2/shipments response. Paths starting with tracked_item are relative to that record. Containers are in tracked_item.data.data.containers[], with events in each container's events[]. In GET /v2/tracking, shipment data is directly under data.
| GoComet | TimeToCargo | Response handling |
|---|---|---|
tracking_id on creation | data.task_id → results[].data.tracking_metadata.id | Save the temporary data.task_id after submission. Once results arrive, map the source tracking_id to the permanent data.results[].data.tracking_metadata.id. |
updated_trackings[] | data.data[] | Iterate over data.data[] instead of updated_trackings[]. These are current records, so do not treat every entry as a new change. |
tracking_id / tracking_number / container_number | id / tracked_item.track_number / tracked_item.data.data.containers[].number | Keep three values distinct: the record id, the requested reference in tracked_item.track_number, and physical container numbers in containers[].number. |
status | tracked_item.data.data.shipment_status | Read shipment progress from tracked_item.data.data.shipment_status. Handle missing data using tracked_item.data.status. |
events[].event | tracked_item.data.data.containers[].events[].status_code | Use the event's status_code. Check the journey stage because gate-in, loading and vessel arrival have different codes. |
events[].actual_datetime / planned_datetime | events[].date / actual | Read the date from date and check actual. When converting historical data, use actual_datetime when present, otherwise planned_datetime. |
Response examples
Each pair labels the former-provider and TimeToCargo responses. Expand the longer JSON examples when you need them; the mapping tables remain visible. These are shortened examples with illustrative data. The path above each JSON block identifies the part shown. Paths in the following table start from that part.
Tracking acceptance
GoComet — POST /api/v1/integrations/add_tracking_number
Shortened response.
{
"tracking_id": "33333333-3333-4333-8333-333333333333",
"message": "Added Successfully",
"status": "success"
}TimeToCargo — POST /v2/tracking/batch
Shortened response.
{
"success": true,
"status": "OK",
"data": {
"task_id": "22222222-2222-4222-8222-222222222222"
}
}How to map
| GoComet | TimeToCargo | Required change |
|---|---|---|
tracking_id = "33333333-3333-4333-8333-333333333333" | data.task_id = "22222222-2222-4222-8222-222222222222" | The GoComet ID identifies tracking, while the new task_id identifies only the background task. Retrieve the permanent ID from the task result. |
status = "success" | status = "OK" | OK means the request was accepted. Check the task result separately to determine whether tracking data was found. |
The creation response contains only the task ID. After PROCESSED, retrieve the permanent ID from data.results[].data.tracking_metadata.id. Use it to locate the stored record and update its label.
Stored tracking and equipment
GoComet — GET /api/v1/integrations/live-tracking
Fragment: updated_trackings[0].
{
"tracking_id": "33333333-3333-4333-8333-333333333333",
"tracking_number": "MSCU1234567",
"container_number": "MSCU1234567",
"carrier_code": "MSCU",
"carrier_name": "MSC",
"reference_no": "Order 123",
"container_size": "40 ft",
"container_type": "High Cube",
"pol_name": "Singapore, SGSIN",
"pod_name": "Rotterdam, NLRTM",
"archived": false,
"other_data": {
"purchase_order": "PO-456"
}
}TimeToCargo — GET /v2/shipments
Fragment: data.data[0].
{
"id": "11111111-1111-4111-8111-111111111111",
"status": "ACTIVE",
"note": "Order 123",
"track_number": "MSCU1234567",
"tracked_item": {
"track_number": "MSCU1234567",
"track_number_type": "container",
"data": {
"success": true,
"status": "OK",
"data": {
"summary": {
"company": {
"name": "MSC",
"scacs": ["MEDU", "MSCU"]
},
"pol": {
"location": 0,
"date": "2026-10-01T12:00:00"
},
"pod": {
"location": 1,
"date": "2026-10-12T08:00:00"
}
},
"locations": [
{
"id": 0,
"name": "Singapore",
"country": "Singapore",
"lat": 1.25,
"lng": 103.75
},
{
"id": 1,
"name": "Rotterdam",
"country": "Netherlands",
"lat": 51.95,
"lng": 4.14
}
],
"containers": [
{
"number": "MSCU1234567",
"type": "40' High Cube"
}
]
}
}
}
}How to map
| GoComet | TimeToCargo | Required change |
|---|---|---|
tracking_id = "33333333-3333-4333-8333-333333333333" | id = "11111111-1111-4111-8111-111111111111" | Store the source and new IDs in one mapping table. Use the new ID in tracking management requests. |
tracking_number = "MSCU1234567" | tracked_item.track_number = "MSCU1234567" | Read the requested reference from tracked_item.track_number. For bill of lading tracking, this is the document reference, not a container number. |
reference_no = "Order 123" | note = "Order 123" | Move the order reference into note after tracking is created. The value must fit within 40 characters. |
container_type = "High Cube" | tracked_item.data.data.containers[0].type = "40' High Cube" | Read size and type from the single containers[].type string. This response has no separate size field. |
pod_name = "Rotterdam, NLRTM" | tracked_item.data.data.locations[1].name = "Rotterdam" | For the discharge port name, find the locations entry whose id matches summary.pod.location. An array index may differ from its ID. |
other_data | No direct equivalent | Keep other_data in your database. The tracking response has no field for arbitrary metadata. |
Actual timestamp and remaining estimate
GoComet — GET /api/v1/integrations/live-tracking
Fragment: updated_trackings[0].
{
"container_number": "MSCU1234567",
"events": [
{
"event": "gate_in",
"carrier_event": "Gate in full",
"location": "SINGAPORE, SG",
"actual_datetime": "01/10/2026 10:00:00",
"planned_datetime": "01/10/2026 09:00:00",
"vessel_details": {
"vessel_name": "",
"voyage_num": null
}
},
{
"event": "arrival",
"carrier_event": "Vessel arrival",
"location": "ROTTERDAM, NL",
"actual_datetime": "",
"planned_datetime": "12/10/2026 08:00:00",
"vessel_details": {
"vessel_name": "EXAMPLE VESSEL",
"voyage_num": "126E"
}
}
]
}TimeToCargo — GET /v2/shipments
Fragment: data.data[0].tracked_item.data.data.
{
"locations": [
{
"id": 0,
"name": "Singapore",
"country": "Singapore",
"lat": 1.25,
"lng": 103.75
},
{
"id": 1,
"name": "Rotterdam",
"country": "Netherlands",
"lat": 51.95,
"lng": 4.14
}
],
"containers": [
{
"number": "MSCU1234567",
"events": [
{
"location": 1,
"status": "Vessel arrival",
"status_code": "VAD",
"date": "2026-10-12T08:00:00",
"actual": false,
"vessel": "EXAMPLE VESSEL",
"voyage": "126E"
},
{
"location": 0,
"status": "Gate in full",
"status_code": "CGI",
"date": "2026-10-01T10:00:00",
"actual": true,
"vessel": null,
"voyage": null
}
]
}
]
}How to map
| GoComet | TimeToCargo | Required change |
|---|---|---|
events[0].actual_datetime = "01/10/2026 10:00:00" | containers[0].events[1].date = "2026-10-01T10:00:00" | When converting this date, parse dd/MM/yyyy HH:mm:ss and set actual=true. This string alone does not identify a time zone. |
events[1].planned_datetime = "12/10/2026 08:00:00" | containers[0].events[0].date = "2026-10-12T08:00:00" | Use the planned date only when the actual date is absent, and set actual=false. |
events[0].event = "gate_in" | containers[0].events[1].status_code = "CGI" | The laden-container gate-in shown here corresponds to CGI. Handle other container operations separately. |
events[1].event = "arrival" | containers[0].events[0].status_code = "VAD" | The vessel arrival shown here corresponds to VAD. Do not treat it as confirmation of container discharge. |
events[1].vessel_details.vessel_name = "EXAMPLE VESSEL" | containers[0].events[0].vessel = "EXAMPLE VESSEL" | Read the vessel name directly from event.vessel instead of vessel_details.vessel_name. |
Parse dd/MM/yyyy HH:mm:ss explicitly. It has no timezone, do not assume UTC. Preserve original forecast history separately.
Tracking exists but data is unavailable
GoComet — GET /api/v1/integrations/live-tracking
Fragment: updated_trackings[0].
{
"tracking_id": "33333333-3333-4333-8333-333333333333",
"tracking_number": "MSCU1234567",
"status": "Data Not Found",
"archived": false,
"events": []
}TimeToCargo — GET /v2/shipments
Fragment: data.data[0].
{
"id": "11111111-1111-4111-8111-111111111111",
"status": "ACTIVE",
"track_number": "MSCU1234567",
"tracked_item": {
"track_number": "MSCU1234567",
"track_number_type": "container",
"data": {
"status": "INFO_NOT_FOUND",
"data": null
}
}
}How to map
| GoComet | TimeToCargo | Required change |
|---|---|---|
status = "Data Not Found" | tracked_item.data.status = "INFO_NOT_FOUND" | Check tracked_item.data.status for INFO_NOT_FOUND. It indicates missing data, not a delivered shipment. |
archived = false | status = "ACTIVE" | With status: "ACTIVE", the subscription remains active even if shipment data has not yet been found. |
events = [] | tracked_item.data.data = null | Check that tracked_item.data.data is not null before accessing containers. An empty response does not confirm shipment completion. |
Data to retain separately
GoComet creation codes are available in its Bulk Upload Template. Map them to SCACs from GET /v2/companies. You can keep one label in note, while tag collections and tag-based searches remain in your system. GoComet schedules, incident data and analytics reports are not transferred into tracking responses.
Last updated on