SeaRates
Migrate from SeaRates to TimeToCargo API v2: authentication, requests and response handling
This guide covers migration from SeaRates Container Tracking API v3 to TimeToCargo API v2. Parameter differences for legacy /container, /reference and /apiv2 operations are listed separately.
Public SeaRates documentation is currently unavailable. Before migrating, confirm your API version and integration parameters in your account or with SeaRates support. The tables below cover v3 unless stated otherwise.
See the migration workflow for importing references and setting up notifications. Full TimeToCargo schemas are in the API reference.
Authentication
SeaRates uses the api_key query parameter. The SeaRates base URL is https://tracking.searates.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
| SeaRates | TimeToCargo | Required change |
|---|---|---|
metadata.number + metadata.type | request.track_number | Read the requested number and type from request.track_number instead of metadata. |
containers[] | data.containers[] | Process each entry in data.containers[]. A bill of lading or booking can return several containers. |
metadata.status | data.shipment_status | Read shipment progress from data.shipment_status. The top-level status describes the request result. |
Operation mapping
| SeaRates | TimeToCargo | Required change |
|---|---|---|
GET /tracking | GET /v2/tracking | Pass the reference, type and carrier. Use POST /v2/tracking/batch for several references. |
GET /info/sealines | GET /v2/companies | Find the carrier in the new directory. Use its scac and check the required reference type in cn, bl or bk. |
GET /route | GET /v2/tracking?need_route=true | Add need_route=true to the tracking request. For stored data, use GET /v2/shipments?need_route=true. |
GET /history, GET /history?id=… | No direct equivalent | Export past SeaRates responses before switching off the service. The shipment list provides current data, not an archive of those responses. |
GET /container, /reference, /apiv2 | GET /v2/tracking | Identify the SeaRates version first. Replace a numeric sealine with a SCAC from GET /v2/companies. |
Request parameters
| SeaRates | TimeToCargo | Required change |
|---|---|---|
number | value | Copy number into the value query parameter without changing the reference. |
type: CT / BL / BK | type: container / bl / bk | Replace CT with container, BL with bl, and BK with bk. Include type in every request. |
sealine | company | Pass the carrier SCAC in company and verify it through GET /v2/companies. AUTO is available only for container numbers. |
route / ais | need_route | Set need_route=true to request route data. Remove ais from the request. There is no separate AIS switch. |
force_update | force_update | Set force_update=true when you need a carrier refresh. Follow the request limits. |
Response fields
Paths in this table start at the root of a GET /v2/tracking response. In /v2/shipments, shipment data is nested inside each record at tracked_item.data.data. See the webhook guide for notification formats.
| SeaRates | TimeToCargo | Response handling |
|---|---|---|
data.metadata.number | request.track_number.value | Read the requested reference from request.track_number.value. Returned container numbers are in data.containers[].number. |
data.metadata.sealine | data.summary.company.scacs[] | Treat scacs as an array of strings. Check array membership instead of comparing it with a single string. |
data.metadata.status | data.shipment_status | Update status handling to use shipment_status values. Vessel arrival, container discharge and delivery are separate stages. |
data.containers[].events[] | data.containers[].events[] | Read the event text from status, its code from status_code, its date from date, and its actual flag from actual. Resolve location through data.locations. |
data.route | data.route_info | Read route geometry from route_info.route[].path and the current point from route_info.current_position. Coordinates use [latitude, longitude]. |
metadata.api_calls / unique_shipments | GET /v2/apikey | Request the remaining tracking allowance through GET /v2/apikey. SeaRates usage counters and balance do not transfer to the new account. |
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.
Reference, tracking type and shipment state
SeaRates — GET /tracking
Shortened response.
{
"status": "success",
"message": "OK",
"data": {
"metadata": {
"number": "MSCU1234567",
"type": "CT",
"sealine": "MSCU",
"sealine_name": "MSC",
"status": "IN_TRANSIT"
},
"containers": [
{
"number": "MSCU1234567",
"iso_code": "45G1",
"size_type": "40' High Cube Dry"
}
]
}
}TimeToCargo — GET /v2/tracking
Shortened response.
{
"success": true,
"status": "OK",
"request": {
"track_number": {
"type": "container",
"value": "MSCU1234567"
},
"company": "MSCU"
},
"data": {
"summary": {
"company": {
"name": "MSC",
"scacs": ["MEDU", "MSCU"]
}
},
"shipment_status": "IN_TRANSIT",
"containers": [
{
"number": "MSCU1234567",
"type": "40' High Cube Dry"
}
],
"tracking_metadata": {
"id": "11111111-1111-4111-8111-111111111111",
"status": "ACTIVE"
}
}
}How to map
| SeaRates | TimeToCargo | Required change |
|---|---|---|
data.metadata.number = "MSCU1234567" | request.track_number.value = "MSCU1234567" | The reference remains MSCU1234567. Read it from request.track_number.value in the new response. |
data.metadata.type = "CT" | request.track_number.type = "container" | SeaRates CT corresponds to container. Use that value when building the request. |
data.metadata.sealine = "MSCU" | data.summary.company.scacs = ["MEDU","MSCU"] | Handle the scacs array instead of a single code. In this example, MSC has both MEDU and MSCU. |
data.metadata.status = "IN_TRANSIT" | data.shipment_status = "IN_TRANSIT" | Shipment progress is IN_TRANSIT. ACTIVE in tracking_metadata.status means the tracking subscription is active. |
data.containers[0].size_type = "40' High Cube Dry" | data.containers[0].type = "40' High Cube Dry" | Read the container size and type description from containers[].type instead of size_type. |
data.containers[0].iso_code = "45G1" | No direct equivalent | There is no separate ISO equipment code field. Keep the source value separately if your system needs it. |
Events, locations and vessel
SeaRates — GET /tracking
Fragment: data.
{
"locations": [
{
"id": 10,
"name": "Singapore",
"country": "Singapore",
"lat": 1.25,
"lng": 103.75
},
{
"id": 20,
"name": "Rotterdam",
"country": "Netherlands",
"lat": 51.95,
"lng": 4.14
}
],
"vessels": [
{
"id": 5,
"name": "EXAMPLE VESSEL"
}
],
"containers": [
{
"number": "MSCU1234567",
"events": [
{
"location": 10,
"description": "Loaded",
"status": "CLL",
"date": "2026-10-01 12:00:00",
"actual": true,
"vessel": 5,
"voyage": "126E"
},
{
"location": 20,
"description": "Vessel arrival",
"status": "VAD",
"date": "2026-10-12 08:00:00",
"actual": false,
"vessel": 5,
"voyage": "126E"
}
]
}
]
}TimeToCargo — GET /v2/tracking
Fragment: 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",
"type": "40' High Cube Dry",
"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": "Loaded",
"status_code": "CLL",
"date": "2026-10-01T12:00:00",
"actual": true,
"vessel": "EXAMPLE VESSEL",
"voyage": "126E"
}
]
}
]
}How to map
| SeaRates | TimeToCargo | Required change |
|---|---|---|
containers[0].events[0].description = "Loaded" | containers[0].events[1].status = "Loaded" | Event text is in status. Replace the access to description. |
containers[0].events[0].status = "CLL" | containers[0].events[1].status_code = "CLL" | Event codes are in status_code. Here, CLL means loading at the origin port and VAD means vessel arrival. |
containers[0].events[1].actual = false | containers[0].events[0].actual = false | Keep checking actual: true indicates an actual event and false a planned event. |
containers[0].events[0].location = 10 | containers[0].events[1].location = 0 | Match event.location to an id in locations. Do not use SeaRates numeric IDs to index the new response. |
containers[0].events[0].vessel = 5 | containers[0].events[1].vessel = "EXAMPLE VESSEL" | Read the vessel name directly from event.vessel. A lookup in a separate vessel array is no longer needed. |
containers[0].events[0].date = "2026-10-01 12:00:00" | containers[0].events[1].date = "2026-10-01T12:00:00" | Parse the date with the T separator. If no time-zone offset is present, do not append Z or assume UTC. |
Data to retain separately
Before switching off SeaRates, export past responses and position history that you need. The TimeToCargo route can contain a current point and route segments, but does not replace an AIS archive or SeaRates request history.
Last updated on